Efetuando login no .NET e no ASP.NET Core

Por Kirk Larkin, Juergen Gutsch e Rick Anderson

Este artigo descreve o registo no .NET tal como se aplica às aplicações ASP.NET Core. Para obter informações detalhadas sobre como iniciar sessão no .NET, consulte Iniciar sessão no .NET.

Para Blazor obter orientações de registo em log, que adicionam ou substituem as orientações neste nó, consulte ASP.NET Core Blazor logging.

Provedores de registro em log

Os provedores de registro armazenam logs, exceto o Console provedor que exibe logs. Por exemplo, o provedor do Azure Application Insights armazena logs no Azure Application Insights. Vários provedores podem ser habilitados.

Os modelos padrão de aplicativo web do ASP.NET Core chamam WebApplication.CreateBuilder, o que adiciona os seguintes provedores de log:

• Console
• Debug
• EventSource
• Registo de Eventos: Apenas Windows

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

O código anterior mostra o Program.cs arquivo criado com os modelos de aplicativo Web ASP.NET Core. As próximas seções fornecem exemplos com base nos modelos de aplicativo Web ASP.NET Core.

O código a seguir substitui o conjunto padrão de provedores de log adicionado por WebApplication.CreateBuilder:

var builder = WebApplication.CreateBuilder(args);
builder.Logging.ClearProviders();
builder.Logging.AddConsole();

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Como alternativa, o código de log anterior pode ser escrito da seguinte maneira:

var builder = WebApplication.CreateBuilder();
builder.Host.ConfigureLogging(logging =>
{
    logging.ClearProviders();
    logging.AddConsole();
});

Para fornecedores adicionais, consulte:

• Provedores de registro internos
• Provedores de registo de terceiros.

Criar logs

Para criar logs, use um objeto obtido através da ILogger<TCategoryName>.

O exemplo a seguir:

• Cria um registrador, ILogger<AboutModel>, que usa uma categoria de log do nome totalmente qualificado do tipo AboutModel. A categoria de log é uma cadeia de caracteres associada a cada log.
• Chama LogInformation para registar ao Information nível. O nível de log indica a gravidade do evento registrado.

public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("About page visited at {DT}", 
            DateTime.UtcNow.ToLongTimeString());
    }
}

Os níveis e categorias são explicados mais detalhadamente mais adiante neste documento.

Para obter informações sobre Blazor, consulte ASP.NET Core loggingBlazor.

Configurar registo de logs

A configuração de log é geralmente fornecida pela secção Logging de ficheiros appsettings.{ENVIRONMENT}.json, onde o espaço reservado {ENVIRONMENT} é o ambiente. O seguinte appsettings.Development.json arquivo é gerado pelos modelos de aplicativo Web ASP.NET Core:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

No JSON anterior:

• As "Default" e "Microsoft.AspNetCore" categorias são especificadas.
• A "Microsoft.AspNetCore" categoria aplica-se a todas as categorias que começam com "Microsoft.AspNetCore". Por exemplo, essa configuração se aplica à "Microsoft.AspNetCore.Routing.EndpointMiddleware" categoria.
• A categoria "Microsoft.AspNetCore" regista a um nível de log Warning e superior.
• Um provedor de log específico não é especificado, portanto, LogLevel aplica-se a todos os provedores de log habilitados, exceto para o Log de Eventos do Windows.

A Logging propriedade pode ter LogLevel e registrar propriedades do provedor. O LogLevel especifica o nível mínimo a ser registrado para categorias selecionadas. No JSON anterior, Information e Warning os níveis de log são especificados. LogLevel indica a gravidade do log e varia de 0 a 6:

Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5 e None = 6.

Quando um LogLevel é especificado, o registo é habilitado para mensagens no nível especificado e superior. No JSON anterior, a Default categoria é registrada para Information e superior. Por exemplo, Information, Warning, Error, e Critical as mensagens são registradas. Se não LogLevel for especificado, o registro em log será padronizado para o Information nível. Para obter mais informações, consulte Log levels.

Uma propriedade de provedor pode especificar uma LogLevel propriedade. LogLevel Sob um provedor, especifica os níveis a registar para esse provedor e substitui as configurações de log que não estão associadas a um provedor. Considere o seguinte appsettings.json arquivo:

{
  "Logging": {
    "LogLevel": { // All providers, LogLevel applies to all the enabled providers.
      "Default": "Error", // Default logging, Error and higher.
      "Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information", // Overrides preceding LogLevel:Default setting.
        "Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
      }
    },
    "EventSource": { // EventSource provider
      "LogLevel": {
        "Default": "Warning" // All categories of EventSource provider.
      }
    }
  }
}

Configurações em Logging.{PROVIDER NAME}.LogLevel substituem configurações em Logging.LogLevel, onde o marcador de posição {PROVIDER NAME} representa o nome do provedor. No JSON anterior, o Debug nível de log padrão do provedor é definido como Information:

Logging:Debug:LogLevel:Default:Information

A configuração anterior especifica o nível de Information log para cada Logging:Debug: categoria, exceto Microsoft.Hosting. Quando uma categoria específica é listada, a categoria específica substitui a categoria padrão. No JSON anterior, as Logging:Debug:LogLevel categorias "Microsoft.Hosting" e "Default" substituem as configurações em Logging:LogLevel.

O nível mínimo de log pode ser especificado para:

• Fornecedores específicos: Por exemplo, Logging:EventSource:LogLevel:Default:Information
• Categorias específicas: Por exemplo, Logging:LogLevel:Microsoft:Warning
• Todos os fornecedores e todas as categorias: Logging:LogLevel:Default:Warning

Quaisquer logs abaixo do nível mínimo não:

• Passado para o fornecedor.
• Registrado ou exibido.

Para suprimir todos os logs, especifique LogLevel.None. LogLevel.None tem um valor de 6, que é superior a LogLevel.Critical (5).

Se um provedor suportar escopos de log, IncludeScopes indica se estão habilitados. Para obter mais informações, consulte escopos de registo.

O arquivo a seguir appsettings.json contém todos os provedores habilitados por padrão:

{
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Error",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information" // Overrides preceding LogLevel:Default setting.
      }
    },
    "Console": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "EventSource": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "EventLog": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "AzureAppServicesFile": {
      "IncludeScopes": true,
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "AzureAppServicesBlob": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Na amostra anterior:

• As categorias e níveis não são valores sugeridos. O exemplo é fornecido para mostrar todos os provedores padrão.
• Configurações em Logging.{PROVIDER NAME}.LogLevel substituem configurações em Logging.LogLevel, onde o marcador de posição {PROVIDER NAME} representa o nome do provedor. Por exemplo, o nível em Debug.LogLevel.Default substitui o nível em LogLevel.Default.
• É usado cada alias de provedor padrão. Cada provedor define um alias que pode ser usado na configuração no lugar do nome do tipo totalmente qualificado. Os aliases de provedores incorporados são:
  • Console
  • Debug
  • EventSource
  • EventLog
  • AzureAppServicesFile
  • AzureAppServicesBlob
  • ApplicationInsights

Iniciar sessão Program.cs

O exemplo a seguir chama Builder.WebApplication.Logger em Program.cs e regista mensagens informativas:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.Logger.LogInformation("Adding Routes");
app.MapGet("/", () => "Hello World!");
app.Logger.LogInformation("Starting the app");
app.Run();

O exemplo a seguir chama AddConsole em Program.cs e regista o endpoint /Test.

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddConsole();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.MapGet("/Test", async (ILogger<Program> logger, HttpResponse response) =>
{
    logger.LogInformation("Testing logging in Program.cs");
    await response.WriteAsync("Testing");
});

app.Run();

O exemplo a seguir chama AddSimpleConsole , desabilita a saída de cores e registra o Program.cs ponto de /Testextremidade:

using Microsoft.Extensions.Logging.Console;

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddSimpleConsole(i => i.ColorBehavior = LoggerColorBehavior.Disabled);

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.MapGet("/Test", async (ILogger<Program> logger, HttpResponse response) =>
{
    logger.LogInformation("Testing logging in Program.cs");
    await response.WriteAsync("Testing");
});

app.Run();

Definir o nível de log por linha de comando, variáveis de ambiente e outras configurações

O nível de log pode ser definido por qualquer um dos provedores de configuração.

O separador : não funciona com chaves hierárquicas de variáveis de ambiente em todas as plataformas. Por exemplo, o separador : não é suportado pelo Bash. O duplo sublinhado, __, é:

• Suportado por todas as plataformas.
• Substituído automaticamente por dois pontos, :.

Os seguintes comandos:

• Defina a chave Logging:LogLevel:Microsoft do ambiente para um valor de Information no Windows.
• Teste as configurações ao usar um aplicativo criado com os modelos de aplicativo Web ASP.NET Core. O comando dotnet run deve ser executado no diretório do projeto depois de usar set.

set Logging__LogLevel__Microsoft=Information
dotnet run

A configuração de ambiente anterior:

• É definido apenas em processos iniciados a partir da janela de comando em que foram definidos.
• Não é lido por navegadores iniciados com o Visual Studio.

O comando setx a seguir também define a chave do ambiente e o valor no Windows. set, ao contrário, setx as configurações são persistentes. O /M switch define a variável no ambiente do sistema. Se /M não for usada, uma variável de ambiente do usuário será definida.

setx Logging__LogLevel__Microsoft Information /M

Considere o seguinte appsettings.json arquivo:

"Logging": {
  "Console": {
    "LogLevel": {
      "Microsoft.Hosting.Lifetime": "Trace"
    }
  }
}

O comando a seguir define a configuração anterior no ambiente:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

Note

Ao configurar variáveis de ambiente com nomes que contêm . (pontos) no macOS e Linux, considere a questão "Exportar uma variável com um ponto (.) nela" no Stack Exchange e a respetiva resposta aceite.

No Serviço de Aplicativo do Azure, selecione Nova configuração de aplicativo na página Configuração de Definições>. As configurações do aplicativo do Serviço de Aplicativo do Azure são:

• Encriptado em repouso e transmitido através de um canal encriptado.
• Expostos como variáveis de ambiente.

Para obter mais informações, consulte Aplicativos do Azure: Substituir a configuração do aplicativo usando o portal do Azure.

Para obter mais informações sobre como definir ASP.NET valores de configuração principais usando variáveis de ambiente, consulte variáveis de ambiente. Para obter informações sobre como usar outras fontes de configuração, incluindo a linha de comando, o Cofre da Chave do Azure, a Configuração do Aplicativo do Azure, outros formatos de arquivo e muito mais, consulte Configuração no ASP.NET Core.

Como as regras de filtragem são aplicadas

Quando um objeto ILogger<TCategoryName> é criado, o objeto ILoggerFactory seleciona uma única regra por provedor para aplicar a esse logger. Todas as mensagens escritas por uma ILogger instância são filtradas com base nas regras selecionadas. A regra mais específica para cada par de provedor e categoria é selecionada entre as regras disponíveis.

O algoritmo a seguir é usado para cada provedor quando um ILogger é criado para uma determinada categoria:

• Selecione todas as regras que correspondam ao provedor ou seu alias. Se não for encontrada nenhuma correspondência, selecione todas as regras cujo provedor esteja vazio.
• A partir do resultado da etapa anterior, selecione as regras com o prefixo de categoria correspondente mais longo. Se nenhuma correspondência for localizada, selecione todas as regras que não especificam nenhuma categoria.
• Se várias regras forem selecionadas, escolha a última .
• Se nenhuma regra estiver selecionada, use MinimumLevel.

Saída de log do comando dotnet run e do Visual Studio

Os logs criados com os provedores de log padrão são exibidos:

• No Visual Studio
  • Na janela de saída de depuração ao fazer o debug.
  • Na janela ASP.NET Core Web Server.
• Na janela do console quando o aplicativo é executado com dotnet run.

Os logs que começam com categorias "Microsoft" são do .NET. .NET e o código da aplicação utilizam a mesma API de registo e os mesmos fornecedores.

Categoria de log

Quando um ILogger objeto é criado, uma categoria é especificada. Essa categoria é incluída em cada mensagem de log criada por essa instância do ILogger. A cadeia de caracteres de categoria é arbitrária, mas a convenção é usar o nome de classe totalmente qualificado. Por exemplo, em um controlador, o nome pode ser "TodoApi.Controllers.TodoController". Os aplicativos Web ASP.NET Core usam ILogger<T> para obter automaticamente uma instância ILogger que usa o nome de tipo totalmente qualificado de T como categoria.

public class PrivacyModel : PageModel
{
    private readonly ILogger<PrivacyModel> _logger;

    public PrivacyModel(ILogger<PrivacyModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.PrivacyModel called.");
    }
}

Se desejar uma categorização adicional, a convenção é usar um nome hierárquico anexando uma subcategoria ao nome de classe totalmente qualificado e especificar explicitamente a categoria usando ILoggerFactory.CreateLogger:

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

    public ContactModel(ILoggerFactory logger)
    {
        _logger = logger.CreateLogger("TodoApi.Pages.ContactModel.MyCategory");
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.ContactModel called.");
    }

Chamar CreateLogger com um nome fixo pode ser útil quando usado em vários métodos para que os eventos possam ser organizados por categoria.

ILogger<T> é equivalente a chamar CreateLogger usando o nome de tipo totalmente qualificado de T.

Nível de log

A tabela a seguir lista os LogLevel valores, o método de extensão de conveniência Log{LogLevel} e o uso sugerido:

LogLevel	Value	Method	Description
Trace	0	LogTrace	Contêm as mensagens mais detalhadas. Essas mensagens podem conter dados confidenciais do aplicativo. Essas mensagens são desabilitadas por padrão e não devem ser habilitadas na produção.
Debug	1	LogDebug	Para depuração e desenvolvimento. Use com cautela na produção devido ao alto volume.
Information	2	LogInformation	Rastreia o fluxo geral do aplicativo. Pode ter valor a longo prazo.
Warning	3	LogWarning	Para eventos anormais ou inesperados. Normalmente, inclui erros ou condições que não fazem com que o aplicativo falhe.
Error	4	LogError	Para erros e exceções que não podem ser tratados. Essas mensagens indicam uma falha na operação ou solicitação atual, não uma falha em todo o aplicativo.
Critical	5	LogCritical	Para falhas que exigem atenção imediata. Exemplos: cenários de perda de dados, sem espaço em disco.
None	6		Especifica que uma categoria de log não deve gravar mensagens.

Na tabela anterior, o LogLevel é listado da menor para a maior gravidade.

O Log primeiro parâmetro do método, LogLevel, indica a gravidade do log. Em vez de chamar Log(LogLevel, ...), a maioria dos desenvolvedores chama os métodos de extensão Log{LOG LEVEL}, onde o marcador {LOG LEVEL} é o nível de log. Por exemplo, as duas chamadas de log a seguir são funcionalmente equivalentes e produzem o mesmo log:

[HttpGet]
public IActionResult Test1(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);

    _logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem é o ID do evento. MyLogEvents faz parte do aplicativo de exemplo e é exibido na seção ID do evento Log .

MyDisplayRouteInfo e ToCtxString são fornecidos pelo pacote NuGet Rick.Docs.Samples.RouteInfo . Os métodos exibem informações de rota Controller e Razor Page.

O código a seguir cria Information e Warning registra:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

No código anterior, o primeiro Log{LOG LEVEL} parâmetro,MyLogEvents.GetItem, é a ID do evento Log. O segundo parâmetro é um modelo de mensagem com espaços reservados para valores de argumento fornecidos pelos parâmetros de método restantes. Os parâmetros do método são explicados na seção de modelo de mensagem mais adiante neste documento.

Chame o método apropriado Log{LOG LEVEL} para controlar a quantidade de saída de log gravada em uma mídia de armazenamento específica. Por exemplo:

• Em produção:
  • O registro em log nos Traceníveis, Debug ou Information produz um grande volume de mensagens de log detalhadas. Para controlar os custos e não exceder os limites de armazenamento de dados, registe mensagens de nível Trace, Debug ou Information num armazenamento de dados de alto volume e baixo custo. Considere limitar Trace, Debugou Information a categorias específicas.
  • O logging em Warning através dos níveis Critical deve produzir poucos registos.
    • Custos e limites de armazenamento geralmente não são uma preocupação.
    • Poucos logs permitem mais flexibilidade nas opções de armazenamento de dados.
• Em desenvolvimento:
  • Definido como Warning.
  • Adicione Trace, Debugou Information mensagens durante a solução de problemas. Para limitar a produção, defina Trace, Debugou Information apenas para as categorias sob investigação.

ASP.NET Core grava logs para eventos da estrutura. Por exemplo, considere a saída de log para:

• Uma Razor aplicação de Páginas criada usando os modelos ASP.NET Core.
• Registro em log definido como Logging:Console:LogLevel:Microsoft:Information.
• Navegação para a Privacy página:

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
      Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
      Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
      Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
      Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
      Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
      Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 149.3023ms 200 text/html; charset=utf-8

Os seguintes conjuntos JSON Logging:Console:LogLevel:Microsoft:Information:

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

ID do evento de log

Cada log pode especificar uma ID de evento. O aplicativo de exemplo usa a classe MyLogEvents para definir IDs de evento.

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Um ID de evento associa um conjunto de eventos. Por exemplo, todos os logs relacionados à exibição de uma lista de itens em uma página podem ser 1001.

O fornecedor de logging pode armazenar o ID do evento num campo de ID, dentro da mensagem de logging, ou não armazená-lo de forma alguma. O provedor de depuração não mostra IDs de evento. O provedor de console mostra IDs de evento entre colchetes após a categoria:

info: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) NOT FOUND

Alguns provedores de log armazenam a ID do evento em um campo, o que permite a filtragem na ID.

Modelo de mensagem de log

Cada API de log usa um modelo de mensagem. O modelo de mensagem pode conter espaços reservados para os quais os argumentos são fornecidos. Use nomes para os espaços reservados, não números.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

A ordem dos parâmetros, não seus nomes de espaço reservado, determina quais parâmetros são usados para fornecer valores de espaço reservado em mensagens de log. No código a seguir, os nomes dos parâmetros estão fora de sequência nos espaços reservados do modelo de mensagem:

var apples = 1;
var pears = 2;
var bananas = 3;

_logger.LogInformation("Parameters: {Pears}, {Bananas}, {Apples}", apples, pears, bananas);

No entanto, os parâmetros são atribuídos aos espaços reservados na ordem: apples, pears, bananas. A mensagem de log reflete a ordem dos parâmetros:

Parameters: 1, 2, 3

Essa abordagem permite que os provedores de log implementem log semântico ou estruturado. Os argumentos em si são passados para o sistema de registro, não apenas para o modelo de mensagem formatada. Isso permite que os provedores de log armazenem os valores de parâmetro como campos. Por exemplo, considere o seguinte método de logger:

_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);

Por exemplo, ao fazer logon no Armazenamento de Tabela do Azure:

• Cada entidade da Tabela do Azure pode ter ID e RequestTime propriedades.
• Tabelas com propriedades simplificam consultas em dados registrados. Por exemplo, uma consulta pode encontrar todos os logs dentro de um intervalo específico RequestTime sem ter que analisar o tempo limite da mensagem de texto.

Exceções de log

Os métodos do registrador têm sobrecargas que usam um parâmetro de exceção:

[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    try
    {
        if (id == 3)
        {
            throw new Exception("Test exception");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
        return NotFound();
    }

    return ControllerContext.MyDisplayRouteInfo();
}

MyDisplayRouteInfo e ToCtxString são fornecidos pelo pacote NuGet Rick.Docs.Samples.RouteInfo . Os métodos exibem informações de rota Controller e Razor Page.

O registo de exceções é específico do fornecedor.

Nível de log padrão

Se o nível de log padrão não estiver definido, o valor padrão do nível de log será Information.

Por exemplo, considere o seguinte aplicativo Web:

• Criado com os modelos de aplicativo Web ASP.NET.
• appsettings.json e appsettings.Development.json suprimido ou renomeado.

Com a configuração anterior, navegar para a página de privacidade ou página inicial produz muitas Trace, Debug e Information mensagens com Microsoft no nome da categoria.

O código a seguir define o nível de log padrão quando o nível de log padrão não está definido na configuração:

var builder = WebApplication.CreateBuilder();
builder.Logging.SetMinimumLevel(LogLevel.Warning);

Geralmente, os níveis de log devem ser especificados na configuração e não no código.

Função de filtro

Uma função de filtro é invocada para todos os provedores e categorias que não têm regras atribuídas a eles por configuração ou código:

var builder = WebApplication.CreateBuilder();
builder.Logging.AddFilter((provider, category, logLevel) =>
{
    if (provider.Contains("ConsoleLoggerProvider")
        && category.Contains("Controller")
        && logLevel >= LogLevel.Information)
    {
        return true;
    }
    else if (provider.Contains("ConsoleLoggerProvider")
        && category.Contains("Microsoft")
        && logLevel >= LogLevel.Information)
    {
        return true;
    }
    else
    {
        return false;
    }
});

O código anterior exibe os logs do console quando a categoria contém Controller ou Microsoft e o nível de log é Information ou superior.

Geralmente, os níveis de log devem ser especificados na configuração e não no código.

ASP.NET Categorias principais

A tabela a seguir contém algumas categorias usadas pelo ASP.NET Core.

Category	Notes
Microsoft.AspNetCore	Diagnóstico geral ASP.NET Core.
Microsoft.AspNetCore.DataProtection	Quais chaves foram consideradas, encontradas e usadas.
Microsoft.AspNetCore.HostFiltering	Anfitriões permitidos.
Microsoft.AspNetCore.Hosting	Quanto tempo as solicitações HTTP levaram para serem concluídas e a que horas elas começaram. Quais assemblies de inicialização de hospedagem foram carregados.
Microsoft.AspNetCore.Mvc	MVC e Razor diagnóstico. Vinculação de modelos, execução de filtros, compilação de visualização, seleção de ações.
Microsoft.AspNetCore.Routing	Informações de correspondência de rota.
Microsoft.AspNetCore.Server	Inicie a conexão, pare e mantenha as respostas ativas. Informações do certificado HTTPS.
Microsoft.AspNetCore.StaticFiles	Arquivos servidos.

Para exibir mais categorias na janela do console, defina appsettings.Development.json o seguinte:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Trace",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Para obter uma lista de categorias do Entity Framework, consulte Categorias de mensagens do EF.

Escopos de log

Um escopo pode agrupar um conjunto de operações lógicas. Esse agrupamento pode ser usado para anexar os mesmos dados a cada log criado como parte de um conjunto. Por exemplo, cada log criado como parte do processamento de uma transação pode incluir o ID da transação.

Um âmbito:

• É um tipo IDisposable que é devolvido pelo método BeginScope.
• Dura até ser descartado.

Os seguintes provedores oferecem suporte a escopos:

• Console
• AzureAppServicesFile e AzureAppServicesBlob

Use um escopo encapsulando em um bloco using as chamadas de logger.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    TodoItem todoItem;
    var transactionId = Guid.NewGuid().ToString();
    using (_logger.BeginScope(new List<KeyValuePair<string, object>>
        {
            new KeyValuePair<string, object>("TransactionId", transactionId),
        }))
    {
        _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

        todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            _logger.LogWarning(MyLogEvents.GetItemNotFound, 
                "Get({Id}) NOT FOUND", id);
            return NotFound();
        }
    }

    return ItemToDTO(todoItem);
}

Provedores de registro internos

ASP.NET Core inclui os seguintes provedores de log como parte da estrutura compartilhada:

• Console
• Debug
• EventSource
• EventLog

Os seguintes provedores de registo são fornecidos pela Microsoft, mas não como parte da estrutura partilhada. Eles devem ser instalados como pacote NuGet adicional.

• AzureAppServicesFile e AzureAppServicesBlob
• ApplicationInsights

ASP.NET Core não inclui um provedor de logs para gravar em arquivos. Para gravar logs em arquivos de um aplicativo ASP.NET Core, considere usar um provedor de log de terceiros.

Para obter informações e stdout depurar o log com o ASP.NET Core Module, consulte Solucionar problemas do ASP.NET Core no Serviço de Aplicativo do Azure e no IIS e ASP.NET ANCM (Core Module) para IIS.

Console

O provedor de Console registra a saída no console. Para obter mais informações sobre como exibir Console logs no desenvolvimento, consulte Logging output from dotnet run e Visual Studio.

Debug

O Debug provedor escreve a saída de log utilizando a classe System.Diagnostics.Debug. Chamadas para System.Diagnostics.Debug.WriteLine gravar no provedor Debug.

No Linux, o local do log do Debug provedor depende da distribuição e pode ser um dos seguintes:

• /var/log/message
• /var/log/syslog

Origem do evento

O provedor de EventSource grava numa fonte de eventos multiplataforma com o nome Microsoft-Extensions-Logging. No Windows, o fornecedor usa ETW.

ferramentas dotnet-trace

A dotnet-trace é uma ferramenta global de Interface de Linha de Comando (CLI) multiplataforma que permite a recolha de traços .NET de um processo em execução. A ferramenta coleta dados do provedor de Microsoft.Extensions.Logging.EventSource usando um LoggingEventSource.

Para obter instruções de instalação, consulte dotnet-trace.

Use a dotnet-trace ferramenta para recolher um rastreio de uma aplicação:

1. Execute o aplicativo com o dotnet run comando.

2. Determine o identificador de processo (PID) do aplicativo .NET:

   dotnet-trace ps
   

   Encontre o PID para o processo que tem o mesmo nome do assembly da aplicação.

3. Execute o dotnet-trace comando.

   Sintaxe geral do comando:

   dotnet-trace collect -p {PID} 
       --providers Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
           :FilterSpecs=\"
               {Logger Category 1}:{Category Level 1};
               {Logger Category 2}:{Category Level 2};
               ...
               {Logger Category N}:{Category Level N}\"
   

   Ao usar um shell de comando do PowerShell, coloque o valor --providers entre aspas simples ('):

   dotnet-trace collect -p {PID} 
       --providers 'Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
           :FilterSpecs=\"
               {Logger Category 1}:{Category Level 1};
               {Logger Category 2}:{Category Level 2};
               ...
               {Logger Category N}:{Category Level N}\"'
   

   Em plataformas que não sejam Windows, adicione a -f speedscope opção para alterar o formato do arquivo de rastreamento de saída para speedscope.

   A tabela a seguir define a palavra-chave:

   Keyword	Description
   1	Registre metaeventos sobre o LoggingEventSource. Não registra eventos do ILogger.
   2	Ativa o evento Message quando ILogger.Log() é chamado. Fornece informações de forma programática (não formatada).
   4	Ativa o evento FormatMessage quando ILogger.Log() é chamado. Fornece a versão formatada da cadeia de caracteres das informações.
   8	Ativa o evento MessageJson quando ILogger.Log() é chamado. Fornece uma representação JSON dos argumentos.

   A tabela a seguir lista os níveis de provedor:

   Nível de Provedor	Description
   0	LogAlways
   1	Critical
   2	Error
   3	Warning
   4	Informational
   5	Verbose

   A análise para um nível de categoria pode ser uma cadeia de caracteres ou um número:

   Valor da categoria nomeado	Valor numérico
   Trace	0
   Debug	1
   Information	2
   Warning	3
   Error	4
   Critical	5

   O nível do provedor e o nível da categoria:

   • Estão em ordem inversa.
   • As constantes de cadeia de caracteres não são todas idênticas.

   Se nenhum FilterSpecs for especificado, a implementação EventSourceLogger tentará converter o nível do fornecedor em um nível de categoria e aplicá-lo a todas as categorias.

   Nível de Provedor	Nível de Categoria
   Verbose(5)	Debug(1)
   Informational(4)	Information(2)
   Warning(3)	Warning(3)
   Error(2)	Error(4)
   Critical(1)	Critical(5)

   Se FilterSpecs forem fornecidas, qualquer categoria incluída na lista usa o nível de categoria codificado lá, todas as outras categorias são filtradas.

   Os seguintes exemplos pressupõem que:

   • Um aplicativo está em execução e chamando logger.LogDebug("12345").
   • O ID do processo (PID) foi definido via set PID=12345, onde 12345 é o PID real.

   Considere o seguinte comando:

   dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5
   

   O comando anterior:

   • Captura mensagens de depuração.
   • Não se aplica a um FilterSpecs.
   • Especifica o nível 5 que mapeia a categoria Depurar.

   Considere o seguinte comando:

   dotnet-trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:5\"
   

   O comando anterior:

   • Não captura mensagens de depuração porque o nível de categoria 5 é Critical.
   • Fornece um FilterSpecsarquivo .

   O comando seguinte captura mensagens de depuração, pois o nível de categoria 1 especifica Debug.

   dotnet-trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:1\"
   

   O comando a seguir captura mensagens de depuração porque a categoria especifica Debug.

   dotnet-trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:Debug\"
   

   FilterSpecs entradas para {Logger Category} e {Category Level} representam condições adicionais de filtragem de log. Entradas FilterSpecs separadas com o caractere ; ponto-e-vírgula.

   Exemplo usando um shell de comando do Windows:

   dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"
   

   O comando anterior ativa:

   • O registrador de origem de eventos para produzir cadeias de caracteres formatadas (4) para erros (2).
   • Microsoft.AspNetCore.Hosting registro em log no nível de Informational log (4).

4. Pare a dotnet-trace ferramenta pressionando a tecla Enter ou Ctrl+C.

   O rastreamento é salvo com o nome trace.nettrace na pasta onde o dotnet-trace comando é executado.

5. Abra o rastreamento com Perfview. Abra o trace.nettrace arquivo e explore os eventos de rastreamento.

Se o aplicativo não construir o host com WebApplication.CreateBuilder, adicione o provedor Event Source à configuração de log do aplicativo.

Para obter mais informações, consulte:

• Utilitário de rastreio para análise de desempenho (dotnet-trace) (documentação .NET)
• Rastreio para utilitário de análise de desempenho (dotnet-trace) (documentação do repositório GitHub dotnet/diagnostics)
• LoggingEventSource
• EventLevel
• Perfview: Útil para visualizar rastreamentos de Fonte de Eventos.

Perfview

Use o utilitário PerfView para coletar e exibir logs. Existem outras ferramentas para visualizar logs ETW, mas o PerfView oferece a melhor experiência para trabalhar com os eventos ETW emitidos pelo ASP.NET Core.

Para configurar o PerfView para coletar eventos registrados por esse provedor, adicione a cadeia de caracteres *Microsoft-Extensions-Logging à lista Provedores Adicionais . Não se esqueça do * no início da string.

Registo de Eventos do Windows

O provedor de EventLog envia a saída de log para o Log de Eventos do Windows. Ao contrário dos outros provedores, o provedor de EventLognão herda as configurações padrão de não-provedor. Se as configurações de log EventLog não forem especificadas, assumirão o padrão LogLevel.Warning.

Para registrar eventos inferiores a LogLevel.Warning, defina explicitamente o nível de log. O exemplo a seguir define o nível de log padrão do Log de Eventos como LogLevel.Information:

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

AddEventLog sobrecargas podem passar em EventLogSettings. Se null ou não especificado, as seguintes configurações padrão são usadas:

• LogName: "Aplicação"
• SourceName: "Tempo de execução do .NET"
• MachineName: O nome da máquina local é usado.

O código a seguir altera o SourceName do valor padrão de ".NET Runtime" para MyLogs:

var builder = WebApplication.CreateBuilder();
builder.Logging.AddEventLog(eventLogSettings =>
{
    eventLogSettings.SourceName = "MyLogs";
});

Serviço de Aplicações do Azure

O Microsoft.Extensions.Logging.AzureAppServices pacote do provedor grava logs em ficheiros de texto no sistema de ficheiros de uma aplicação no Azure App Service e no armazenamento de BLOB em uma conta de armazenamento do Azure.

O pacote do provedor não está incluído na estrutura compartilhada. Para usar o provedor, adicione o pacote do provedor ao projeto.

Para definir as configurações do provedor, use AzureFileLoggerOptions e AzureBlobLoggerOptions, conforme mostrado no exemplo a seguir:

using Microsoft.Extensions.Logging.AzureAppServices;

var builder = WebApplication.CreateBuilder();
builder.Logging.AddAzureWebAppDiagnostics();
builder.Services.Configure<AzureFileLoggerOptions>(options =>
{
    options.FileName = "azure-diagnostics-";
    options.FileSizeLimit = 50 * 1024;
    options.RetainedFileCountLimit = 5;
});
builder.Services.Configure<AzureBlobLoggerOptions>(options =>
{
    options.BlobName = "log.txt";
});

Quando é implantado no Serviço de Aplicações do Azure, a aplicação usa as configurações na seção registos do Serviço de Aplicações da página Serviço de Aplicações do portal do Azure. Quando as configurações a seguir são atualizadas, as alterações entram em vigor imediatamente, sem exigir uma reinicialização ou reimplantação do aplicativo.

• Registo de Aplicações (Sistema de Ficheiros)
• Registo de Aplicações (Blob)

O local padrão para ficheiros de log é a pasta D:\\home\\LogFiles\\Application, e o nome de ficheiro padrão é diagnostics-yyyymmdd.txt. O limite de tamanho de arquivo padrão é de 10 MB e o número máximo padrão de arquivos retidos é 2. O nome de blob padrão é {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Esse provedor só registra quando o projeto é executado no ambiente do Azure.

Streaming de log do Azure

O streaming de registos do Azure suporta a visualização da atividade de registo em tempo real de:

• O servidor de aplicativos
• O servidor web
• Falha no rastreamento do pedido

Para configurar o streaming de log do Azure:

• No portal do aplicativo, navegue até a página de logs do Serviço de Aplicativo .
• Defina o Registo de Aplicação (Sistema de Arquivos) para ligado.
• Escolha o log Nível. Essa configuração só se aplica ao streaming de log do Azure.

Navegue até a página Log Stream para visualizar os logs. O registo das mensagens é feito através da interface ILogger.

Azure Application Insights

O Microsoft.Extensions.Logging.ApplicationInsights pacote do provedor grava logs no Azure Application Insights. O Application Insights é um serviço que monitora um aplicativo Web e fornece ferramentas para consultar e analisar os dados de telemetria. Se você usar esse provedor, poderá consultar e analisar seus logs usando as ferramentas do Application Insights.

O provedor de log está incluído como uma dependência do Microsoft.ApplicationInsights.AspNetCore, que é o pacote que fornece toda a telemetria disponível para ASP.NET Core. Se você usar este pacote, não será necessário instalar o pacote do provedor.

O Microsoft.ApplicationInsights.Web pacote é para ASP.NET 4.x, não ASP.NET Core.

Para obter mais informações, consulte os seguintes recursos:

• Visão geral do Application Insights
• Application Insights for ASP.NET Core applications: comece aqui se quiser implementar a gama completa de telemetria do Application Insights junto com o registro.
• ApplicationInsightsLoggerProvider for .NET ILogger logs: Comece aqui se quiser implementar o provedor de log sem o restante da telemetria do Application Insights.
• Adaptadores de registo do Application Insights
• Instale, configure e inicialize o tutorial interativo do SDK do Application Insights .

Provedores de registro de terceiros

Estruturas de log de terceiros que funcionam com o ASP.NET Core:

• elmah.io (repositório GitHub)
• Gelf (repositório GitHub)
• JSNLog (repositório GitHub)
• KissLog.net (repositório GitHub)
• Log4Net (repositório GitHub)
• NLog (repositório GitHub)
• PLogger (repositório GitHub)
• Sentinela (repositório GitHub)
• Serilog (repositório GitHub)
• Stackdriver (repositório Github)

Algumas estruturas de terceiros podem executar log semântico, também conhecido como log estruturado.

O uso de uma estrutura de terceiros é semelhante ao uso de um dos provedores internos:

1. Adicione um pacote NuGet ao seu projeto.
2. Chame um ILoggerFactory método de extensão fornecido pela estrutura de log.

Para obter mais informações, consulte a documentação de cada provedor. Os fornecedores de registo de terceiros não são suportados pela Microsoft.

Nenhum método de registo assíncrono

O registro em log deve ser tão rápido que não vale a pena o custo de desempenho do código assíncrono. Se um armazenamento de dados de registos estiver lento, não escreva diretamente nele. Considere gravar as mensagens de log em um armazenamento rápido inicialmente e, em seguida, movê-las para o armazenamento lento mais tarde. Por exemplo, ao registar no log no SQL Server, não faça isso diretamente num método Log, pois os métodos Log são síncronos. Em vez disso, adicione mensagens de log de forma síncrona a uma fila na memória e peça a um operador em segundo plano que retire as mensagens da fila para fazer o trabalho assíncrono de enviar dados por push para o SQL Server. Para obter mais informações, consulte Orientação sobre como fazer logon em uma fila de mensagens para armazenamentos de dados lentos (dotnet/AspNetCore.Docs #11801).

Alterar os níveis de log em um aplicativo em execução

A API de Logging não inclui um cenário para alterar os níveis de log enquanto uma aplicação está em execução. No entanto, alguns fornecedores de configuração são capazes de recarregar a configuração, o que tem efeito imediato na configuração de registo. Por exemplo, o Provedor de Configuração de Arquivo recarrega a configuração de log por padrão. Se a configuração for alterada no código enquanto uma aplicação está em execução, a aplicação pode chamar IConfigurationRoot.Reload para atualizar a configuração de registo da aplicação.

ILogger e ILoggerFactory

As interfaces e implementações ILogger<TCategoryName> e ILoggerFactory estão incluídas no SDK do .NET. Eles também estão disponíveis nos seguintes pacotes NuGet:

• As interfaces estão em Microsoft.Extensions.Logging.Abstractions.
• As implementações padrão estão em Microsoft.Extensions.Logging.

Aplicar regras de filtro de log no código

A abordagem preferida para definir regras de filtro de log é usando Configuração.

O exemplo a seguir mostra como registrar regras de filtro no código:

using Microsoft.Extensions.Logging.Console;
using Microsoft.Extensions.Logging.Debug;

var builder = WebApplication.CreateBuilder();
builder.Logging.AddFilter("System", LogLevel.Debug);
builder.Logging.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information);
builder.Logging.AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace);

logging.AddFilter("System", LogLevel.Debug)Especifica a categoria e o nível Systemde Debug log . O filtro é aplicado a todos os provedores porque um provedor específico não foi configurado.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) especifica:

• O Debug provedor de registro.
• Nível de log Information e superior.
• Todas as categorias começando com "Microsoft".

Registre automaticamente o escopo com SpanId, TraceId, ParentId, Baggagee Tags.

As bibliotecas de log criam implicitamente um objeto de escopo com SpanId, TraceId, ParentId,Baggage, e Tags. Esse comportamento é configurado via ActivityTrackingOptions.

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddSimpleConsole(options =>
{
    options.IncludeScopes = true;
});

builder.Logging.Configure(options =>
{
    options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
                                       | ActivityTrackingOptions.TraceId
                                       | ActivityTrackingOptions.ParentId
                                       | ActivityTrackingOptions.Baggage
                                       | ActivityTrackingOptions.Tags;
});
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Se o cabeçalho HTTP da traceparent solicitação estiver definido, o ParentId no escopo do log mostrará o W3C parent-id do cabeçalho de entrada traceparent, e o SpanId no escopo do log mostrará o parent-id atualizado para a próxima etapa de saída. Para obter mais informações, consulte Mutando o campo traceparent.

Criar um registador personalizado

Para criar um registrador personalizado, consulte Implementar um provedor de log personalizado no .NET.

Recursos adicionais

• Melhorando o desempenho de registo com geradores de código-fonte
• [LogProperties]
• Repositório Microsoft.Extensions.Logging no GitHub
• Visualize ou baixe o código de exemplo (como fazer o download).
• Registro de alto desempenho
• Os bugs de registro devem ser criados no dotnet/runtime repositório GitHub.
• Blazor registo do