Skip to content

6. Escopos de dados

Uma aplicação web atende muitos usuários ao mesmo tempo, e cada usuário faz numerosas requisições. Os dados podem, portanto, ser compartilhados em três níveis, conhecidos como seu escopo:

  • Escopo de aplicação: os dados são compartilhados por todos os usuários durante todo o tempo de vida do servidor (a lista de médicos, por exemplo);
  • Escopo de requisição: os dados existem apenas durante uma requisição (o modelo de uma view);
  • Escopo de cliente: os dados são específicos de um usuário e devem persistir de uma requisição para a seguinte (o idioma selecionado, o usuário logado).

O curso original ([ASP.NET MVC], 2013) usava uma sessão para este último escopo: um espaço de memória, mantido pelo servidor, específico de cada navegador. O [ASP.NET Core] ainda usa essa abordagem ([AddSession]), mas este documento, assim como o estudo de caso, dispensa esse recurso: os dados de escopo de cliente são armazenados pelo navegador em cookies. O servidor não retém nenhum dado entre as requisições de um mesmo usuário: diz-se que ele não mantém estado ([stateless]). É isso que torna possível, por exemplo, executar vários servidores idênticos atrás de um balanceador de carga. A contrapartida: um cookie está sob o controle do usuário, que pode lê-lo e modificá-lo. Por isso, só são armazenados ali dados não sensíveis — ou dados assinados ou criptografados pelo servidor, que pode então detectar qualquer modificação: é o caso do cookie do [TempData] (Exemplo 20) e do token de autenticação (Capítulo 8).

No lado do servidor, os escopos de aplicação e de requisição correspondem aos ciclos de vida dos serviços de injeção de dependência (veja o Exemplo 06). O [ASP.NET Core] tem três deles:

Registro
Ciclo de vida
Uma instância...
AddSingleton
aplicação
durante todo o tempo de vida da aplicação, compartilhada por todas as requisições
AddScoped
requisição
por requisição HTTP, compartilhada por todos que a solicitam durante essa requisição
AddTransient
nenhum
A cada injeção: duas requisições, duas instâncias

6.1. Exemplo 23: três escopos

O arquivo [Services/CounterService.cs]:

namespace Example23.Services;

// escopo de APLICAÇÃO (AddSingleton): uma única instância, compartilhada por
// TODAS as requisições de TODOS os usuários
public class CounterService
{
    private int total;

    // várias requisições podem ser executadas AO MESMO TEMPO: Interlocked
    // garante que dois incrementos simultâneos não se percam
    public int Increment() => Interlocked.Increment(ref total);
}
  • Linha 7: o serviço será um singleton (veja [Program.cs]): seu campo [total] tem, portanto, escopo de aplicação;
  • linha 11: um servidor web processa várias requisições simultaneamente, em várias threads ([threads]). Se duas requisições executam [total++] ao mesmo tempo, ambas podem ler o mesmo valor, e um incremento é perdido. [Interlocked.Increment] realiza a leitura, a soma e a escrita em uma única operação indivisível. Um serviço singleton deve sempre se precaver contra esses acessos simultâneos.

O arquivo [Services/RequestService.cs]:

namespace Example23.Services;

// escopo de REQUISIÇÃO (AddScoped): uma NOVA instância para cada requisição HTTP,
// compartilhada por todos que a solicitam DURANTE essa requisição
public class RequestService
{
    private static int createdInstances; // static: um contador compartilhado por todas as instâncias

    public int Number { get; } = Interlocked.Increment(ref createdInstances);
}
  • linha 7: um campo declarado como [static] pertence à classe, não a uma instância; ele é compartilhado por todas as instâncias. Ele conta o número de instâncias criadas;
  • linha 9: cada instância recebe um número ao ser criada. O serviço terá escopo de requisição: o número muda a cada requisição.

O arquivo [Services/ToolService.cs]:

namespace Example23.Services;

// escopo TRANSIENT (AddTransient): uma NOVA instância a CADA injeção,
// mesmo durante uma única requisição
public class ToolService
{
    private static int createdInstances;

    public int Number { get; } = Interlocked.Increment(ref createdInstances);
}

O mesmo contador de instâncias, para um serviço [transient].

O arquivo [Program.cs]:

using System.Text.Encodings.Web;
using System.Text.Unicode;
using Example23.Services;
using Microsoft.Extensions.FileProviders;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();
builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All));
// os três tempos de vida de um serviço
builder.Services.AddSingleton<CounterService>(); // uma instância para toda a aplicação
builder.Services.AddScoped<RequestService>();    // uma instância por requisição
builder.Services.AddTransient<ToolService>();    // uma instância por injeção

var app = builder.Build();

app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(Path.GetFullPath(Path.Combine(builder.Environment.ContentRootPath, "..", "common", "bootstrap"))),
    RequestPath = "/bootstrap",
});

// escopo de REQUISIÇÃO: HttpContext.Items nasce e morre com a requisição
app.Use(async (context, next) =>
{
    context.Items["start"] = DateTime.Now.ToString("HH:mm:ss.fff");
    await next(context);
});

app.MapControllers();
app.Run();
  • Linhas 10–12: os três ciclos de vida;
  • Linhas 23–26: um middleware armazena o horário de recebimento da requisição em ***[HttpContext.Items], um dicionário que é criado e destruído junto com a requisição. Tudo o que processa a requisição (filtros, controller, view) pode ler e escrever nele. É o equivalente de [res.locals]* no [Express].

O arquivo [Controllers/ScopesController.cs]:

using Example23.Services;
using Microsoft.AspNetCore.Mvc;

namespace Example23.Controllers;

public record ScopesModel(int Total, int Instance, int Tool, int MyVisits);

public class ScopesController(CounterService counter, RequestService request, ToolService tool) : Controller
{
    [HttpGet("/")]
    public IActionResult Scopes()
    {
        // escopo de CLIENTE: um dado mantido pelo NAVEGADOR (cookie),
        // reenviado ao servidor a cada requisição
        int.TryParse(Request.Cookies["myVisits"], out var myVisits);
        myVisits++;
        Response.Cookies.Append("myVisits", myVisits.ToString(),
            new CookieOptions { HttpOnly = true, SameSite = SameSiteMode.Lax });
        return View(new ScopesModel(counter.Increment(), request.Number, tool.Number, myVisits));
    }
}
  • linha 8: os três serviços são injetados;
  • linhas 15–18: o escopo de cliente: um contador armazenado em um cookie. [Request.Cookies["myVisits"]] lê o cookie enviado pelo navegador ([null] na primeira visita). [int.TryParse] o converte em inteiro; se a conversão falhar, [myVisits] recebe 0. A action o incrementa e redefine o cookie;
  • linha 19: os valores são passados à view.

O arquivo [Views/Scopes/Scopes.cshtml]:

@model ScopesModel
@* @inject: a view também pede os serviços, durante a MESMA requisição *@
@inject RequestService RequestOfTheView
@inject ToolService ToolOfTheView
<h1 class="h3">The scopes of data</h1>
<ul>
  <li>application: @Model.Total visit(s) to the site, all browsers combined</li>
  <li>request: instance no. @Model.Instance of RequestService (no. @RequestOfTheView.Number in the view),
    request received at @Context.Items["start"]</li>
  <li>transient: instance no. @Model.Tool of ToolService (no. @ToolOfTheView.Number in the view)</li>
  <li>client: @Model.MyVisits visit(s) from this browser</li>
</ul>
  • linhas 3–4: a diretiva [@inject Type Name] solicita um serviço ao injetor de dependência e o armazena em uma propriedade da view. A view é executada durante a mesma requisição que a action: poderemos comparar as instâncias recebidas pelo controller e pela view;
  • Linha 9: o valor de escopo de requisição, definido pelo middleware.

Uma página, na URL http://localhost:5000/:

Image

Vamos simular dois navegadores com o [curl] e dois arquivos de cookies, [a.txt] e [b.txt]. O navegador A faz duas requisições, depois o navegador B faz uma e, por fim, A faz mais uma:

1
2
3
4
curl -c a.txt -b a.txt http://localhost:5000/
curl -c a.txt -b a.txt http://localhost:5000/
curl -c b.txt -b b.txt http://localhost:5000/
curl -c a.txt -b a.txt http://localhost:5000/
browser A:
application: 1 visit(s) to the site, all browsers combined
request: instance no. 1 of RequestService (no. 1 in the view), request received at 12:19:46.574
transient: instance no. 1 of ToolService (no. 2 in the view)
client: 1 visit(s) from this browser

browser A:
application: 2 visit(s) to the site, all browsers combined
request: instance no. 2 of RequestService (no. 2 in the view), request received at 12:19:46.671
transient: instance no. 3 of ToolService (no. 4 in the view)
client: 2 visit(s) from this browser

browser B:
application: 3 visit(s) to the site, all browsers combined
request: instance no. 3 of RequestService (no. 3 in the view), request received at 12:19:46.687
transient: instance no. 5 of ToolService (no. 6 in the view)
client: 1 visit(s) from this browser

browser A:
application: 4 visit(s) to the site, all browsers combined
request: instance no. 4 of RequestService (no. 4 in the view), request received at 12:19:46.696
transient: instance no. 7 of ToolService (no. 8 in the view)
client: 3 visit(s) from this browser

(apenas os itens da lista são mostrados). Observamos que:

  • o contador da aplicação conta todas as visitas: 1, 2, 3, 4;
  • cada requisição tem sua própria instância de [RequestService]: 1, 2, 3, 4. Durante uma requisição, o controller e a view recebem a mesma instância;
  • cada injeção de [ToolService] cria uma instância: o controller e a view recebem duas diferentes, e cada requisição cria duas novas;
  • o contador de cliente é específico de cada navegador: A tem 3 visitas, B tem 1.

O cookie é controlado pelo cliente, que pode enviar o valor que quiser:

curl -i -b "myVisits=41" http://localhost:5000/
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Set-Cookie: myVisits=42; path=/; samesite=lax; httponly

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Scopes</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
</head>
<body>
  <div class="container py-3">
    <h1 class="h3">The scopes of data</h1>
<ul>
  <li>application: 6 visit(s) to the site, all browsers combined</li>
  <li>request: instance no. 6 of RequestService (no. 6 in the view),
    request received at 12:19:47.374</li>
  <li>transient: instance no. 11 of ToolService (no. 12 in the view)</li>
  <li>client: 42 visit(s) from this browser</li>
</ul>

  </div>
</body>
</html>

Para um contador de visitas, isso é irrelevante. Para dados sensíveis (a identidade do usuário, seu papel), o servidor precisa ser capaz de detectar adulterações: o Capítulo 8 mostra como.

Dessas durações decorre uma regra: um serviço não deve depender de um serviço com ciclo de vida mais curto. Um singleton que receba um serviço como [Scoped] o manteria indefinidamente, bem além da requisição para a qual ele foi criado. O [ASP.NET Core] verifica o cumprimento dessa regra na inicialização, em modo de desenvolvimento, e se recusa a iniciar se ela for violada. No estudo de caso:

Escopo
Dados
Onde?
aplicação
listas de médicos e clientes, dicionários, CAPTCHAs pendentes, contadores de tentativas
Serviços singleton ([ListCache], [Translator], [CaptchaService]...)
Requisição
acesso ao banco de dados ([DbContext]), repositórios, camada de negócio, modelo de view comum; usuário logado
Serviços [Scoped] ([RdvMedecinsDbContext], [BusinessService], [ApplicationModel]...) ; [HttpContext.User], [HttpContext.Items]
cliente
token de autenticação, idioma, mensagem flash
cookies