Registros en .NET Core y ASP.NET CoreLogging in .NET Core and ASP.NET Core

Por Tom Dykstra y Steve SmithBy Tom Dykstra and Steve Smith

.NET Core es compatible con una API de registro que funciona con una gran variedad de proveedores de registro integrados y de terceros..NET Core supports a logging API that works with a variety of built-in and third-party logging providers. En este artículo se muestra cómo usar las API de registro con proveedores integrados.This article shows how to use the logging API with built-in providers.

La mayoría de los ejemplos de código que se muestran en este artículo son de aplicaciones de ASP.NET Core.Most of the code examples shown in this article are from ASP.NET Core apps. Las partes específicas de registro de estos fragmentos de código son válidas para cualquier aplicación de .NET Core que use el host genérico.The logging-specific parts of these code snippets apply to any .NET Core app that uses the Generic Host. Para ver un ejemplo de cómo usar el host genérico en una aplicación de consola que no sea web, vea el archivo Program.cs de la aplicación de ejemplo de tareas en segundo plano (Tareas en segundo plano con servicios hospedados en ASP.NET Core).For an example of how to use the Generic Host in a non-web console app, see the Program.cs file of the Background Tasks sample app (Tareas en segundo plano con servicios hospedados en ASP.NET Core).

El código de registro para las aplicaciones sin un host genérico es distinto en la forma en que se agregan los proveedores y se crean los registradores.Logging code for apps without Generic Host differs in the way providers are added and loggers are created. Los ejemplos de código que no sean de host se muestran en esas secciones del artículo.Non-host code examples are shown in those sections of the article.

Vea o descargue el código de ejemplo (cómo descargarlo)View or download sample code (how to download)

Incorporación de proveedoresAdd providers

Un proveedor de registro muestra o almacena registros.A logging provider displays or stores logs. Por ejemplo, el proveedor de consola muestra los registros en la consola y el proveedor de Azure Application Insights los almacena en Azure Application Insights.For example, the Console provider displays logs on the console, and the Azure Application Insights provider stores them in Azure Application Insights. Los registros se pueden enviar a varios destinos mediante la incorporación de varios proveedores.Logs can be sent to multiple destinations by adding multiple providers.

Para agregar un proveedor en una aplicación que use un host genérico, llame al método de extensión Add{provider name} del proveedor en Program.cs:To add a provider in an app that uses Generic Host, call the provider's Add{provider name} extension method in Program.cs:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

En una aplicación de consola que no sea de host, llame al método de extensión Add{provider name} del proveedor al crear un elemento LoggerFactory:In a non-host console app, call the provider's Add{provider name} extension method while creating a LoggerFactory:

var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddFilter("Microsoft", LogLevel.Warning)
        .AddFilter("System", LogLevel.Warning)
        .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
        .AddConsole()
        .AddEventLog();
});
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Example log message");

LoggerFactory y AddConsole necesitan una instrucción using para Microsoft.Extensions.Logging.LoggerFactory and AddConsole require a using statement for Microsoft.Extensions.Logging.

Las plantillas de proyecto predeterminadas de ASP.NET Core llaman a CreateDefaultBuilder, que agrega los siguientes proveedores de registro:The default ASP.NET Core project templates call CreateDefaultBuilder, which adds the following logging providers:

Puede reemplazar los proveedores predeterminados por sus propios valores.You can replace the default providers with your own choices. Llame a ClearProviders y agregue los proveedores que desee.Call ClearProviders, and add the providers you want.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Para usar un proveedor, llame al método de extensión Add{provider name} del proveedor en Program.cs:To add a provider, call the provider's Add{provider name} extension method in Program.cs:

public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            var env = hostingContext.HostingEnvironment;
            config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                  .AddJsonFile($"appsettings.{env.EnvironmentName}.json", 
                      optional: true, reloadOnChange: true);
            config.AddEnvironmentVariables();
        })
        .ConfigureLogging((hostingContext, logging) =>
        {
            // Requires `using Microsoft.Extensions.Logging;`
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
            logging.AddDebug();
            logging.AddEventSourceLogger();
        })
        .UseStartup<Startup>()
        .Build();

    webHost.Run();
}

El código anterior requiere referencias a Microsoft.Extensions.Logging y Microsoft.Extensions.Configuration.The preceding code requires references to Microsoft.Extensions.Logging and Microsoft.Extensions.Configuration.

La plantilla de proyecto predeterminada llama a CreateDefaultBuilder, que agrega los siguientes proveedores de registro:The default project template calls CreateDefaultBuilder, which adds the following logging providers:

  • ConsolaConsole
  • DepuraciónDebug
  • EventSource (a partir de ASP.NET Core 2.2)EventSource (starting in ASP.NET Core 2.2)
public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>();

Si usa CreateDefaultBuilder, puede reemplazar los proveedores predeterminados por sus propios valores.If you use CreateDefaultBuilder, you can replace the default providers with your own choices. Llame a ClearProviders y agregue los proveedores que desee.Call ClearProviders, and add the providers you want.

public static void Main(string[] args)
{
    var host = CreateWebHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

Obtenga más información sobre los proveedores de registro integrados y los proveedores de registro de terceros más adelante en el artículo.Learn more about built-in logging providers and third-party logging providers later in the article.

Creación de registrosCreate logs

Para crear registros, use un objeto de ILogger<TCategoryName>.To create logs, use an ILogger<TCategoryName> object. En una aplicación web o servicio hospedado, obtenga un elemento ILogger de la inserción de dependencias.In a web app or hosted service, get an ILogger from dependency injection (DI). En aplicaciones de consola que no sean de host, use LoggerFactory para crear un elemento ILogger.In non-host console apps, use the LoggerFactory to create an ILogger.

En el ejemplo siguiente de ASP.NET Core, se crea un registrador con TodoApiSample.Pages.AboutModel como la categoría.The following ASP.NET Core example creates a logger with TodoApiSample.Pages.AboutModel as the category. La categoría de registro es una cadena que está asociada con cada registro.The log category is a string that is associated with each log. La instancia de ILogger<T> proporcionada por la inserción de dependencias genera registros que tienen el nombre completo del tipo T como la categoría.The ILogger<T> instance provided by DI creates logs that have the fully qualified name of type T as the category.

public class AboutModel : PageModel
{
    private readonly ILogger _logger;

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

En el siguiente ejemplo de aplicación de consola que no es de host, se crea un registrador con LoggingConsoleApp.Program como la categoría.The following non-host console app example creates a logger with LoggingConsoleApp.Program as the category.

var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddFilter("Microsoft", LogLevel.Warning)
        .AddFilter("System", LogLevel.Warning)
        .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
        .AddConsole()
        .AddEventLog();
});
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Example log message");
public class AboutModel : PageModel
{
    private readonly ILogger _logger;

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

En los siguientes ejemplos de aplicación de consola y ASP.NET Core, el registrador se usa para crear registros con Information como el nivel.In the following ASP.NET Core and console app examples, the logger is used to create logs with Information as the level. El nivel de registro indica la gravedad del evento registrado.The Log level indicates the severity of the logged event.

public void OnGet()
{
    Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
    _logger.LogInformation("Message displayed: {Message}", Message);
}
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddFilter("Microsoft", LogLevel.Warning)
        .AddFilter("System", LogLevel.Warning)
        .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
        .AddConsole()
        .AddEventLog();
});
ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogInformation("Example log message");
public void OnGet()
{
    Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
    _logger.LogInformation("Message displayed: {Message}", Message);
}

Los niveles y las categorías se explican detalladamente más adelante en este artículo.Levels and categories are explained in more detail later in this article.

Crear registros en la clase del programaCreate logs in the Program class

Para escribir registros en la clase Program de una aplicación de ASP.NET Core, obtenga una instancia de ILogger desde la inserción de dependencias después de generar el host:To write logs in the Program class of an ASP.NET Core app, get an ILogger instance from DI after building the host:

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    IMyService myService = host.Services.GetRequiredService<IMyService>();
    myService.WriteLog("Logged from MyService.");

    host.Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

No se admite directamente el registro durante la construcción del host.Logging during host construction isn't directly supported. Sin embargo, se puede usar un registrador independiente.However, a separate logger can be used. En el ejemplo siguiente, se usa un registrador Serilog para registrarse en CreateHostBuilder.In the following example, a Serilog logger is used to log in CreateHostBuilder. AddSerilog usa la configuración estática especificada en Log.Logger:AddSerilog uses the static configuration specified in Log.Logger:

using System;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var builtConfig = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .AddCommandLine(args)
            .Build();

        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .WriteTo.File(builtConfig["Logging:FilePath"])
            .CreateLogger();

        try
        {
            return Host.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddRazorPages();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {   
                    logging.AddSerilog();
                })
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

            throw;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}

Crea registros en la clase de inicioCreate logs in the Startup class

Para escribir registros en el método Startup.Configure de una aplicación de ASP.NET Core, incluya un parámetro ILogger en la signatura del método:To write logs in the Startup.Configure method of an ASP.NET Core app, include an ILogger parameter in the method signature:

public void Configure(IApplicationBuilder app, IHostEnvironment env, ILogger<Startup> logger)
{
    if (env.IsDevelopment())
    {
        logger.LogInformation("In Development environment");
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

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

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapRazorPages();
    });
}

No se admite la escritura de registros antes de la finalización del contenedor de inserción de dependencias configurado en el método Startup.ConfigureServices:Writing logs before completion of the DI container setup in the Startup.ConfigureServices method is not supported:

  • No se admite la inyección del registrador en el constructor Startup.Logger injection into the Startup constructor is not supported.
  • No se admite la inyección del registrador en la signatura del método Startup.ConfigureServices.Logger injection into the Startup.ConfigureServices method signature is not supported

El motivo de esta restricción es que los registros dependen de la inserción de dependencias y de la configuración, que a su vez depende de la inserción de dependencias.The reason for this restriction is that logging depends on DI and on configuration, which in turns depends on DI. El contenedor de inserción de dependencias no se configura hasta que finaliza ConfigureServices.The DI container isn't set up until ConfigureServices finishes.

La inserción del constructor de un registrador en Startup funciona en versiones anteriores de ASP.NET Core, ya que se crea un contenedor de inserción de dependencias independiente para el host de web.Constructor injection of a logger into Startup works in earlier versions of ASP.NET Core because a separate DI container is created for the Web Host. Para conocer por qué solo se crea un contenedor para el host genérico, vea el anuncio de cambios importantes.For information about why only one container is created for the Generic Host, see the breaking change announcement.

Si necesita configurar un servicio que dependa de ILogger<T>, puede hacerlo si usa la inserción del constructor, o bien si proporciona un Factory Method.If you need to configure a service that depends on ILogger<T>, you can still do that by using constructor injection or by providing a factory method. Usar un Factory Method es la opción recomendada si no tiene otra alternativa.The factory method approach is recommended only if there is no other option. Por ejemplo, imagine que necesita rellenar una propiedad con un servicio desde la inserción de dependencias:For example, suppose you need to fill a property with a service from DI:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddRazorPages();

    services.AddSingleton<IMyService>((container) =>
    {
        var logger = container.GetRequiredService<ILogger<MyService>>();
        return new MyService() { Logger = logger };
    });

    services.AddSingleton<ITodoRepository, TodoRepository>();
}

El código resaltado anterior es un elemento Func que se ejecuta la primera vez que el contenedor de inserción de dependencias necesita crear una instancia de MyService.The preceding highlighted code is a Func that runs the first time the DI container needs to construct an instance of MyService. Puede acceder a cualquiera de los servicios registrados de esta forma.You can access any of the registered services in this way.

Creación de registros durante el inicioCreate logs in Startup

Para escribir registros en la clase Startup, incluya un parámetro ILogger en la signatura de construcción:To write logs in the Startup class, include an ILogger parameter in the constructor signature:

public class Startup
{
    private readonly ILogger _logger;

    public Startup(IConfiguration configuration, ILogger<Startup> logger)
    {
        Configuration = configuration;
        _logger = logger;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        // Add our repository type
        services.AddSingleton<ITodoRepository, TodoRepository>();
        _logger.LogInformation("Added TodoRepository to services");
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            _logger.LogInformation("In Development environment");
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

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

        app.UseMvc();
    }
}

Crear registros en la clase del programaCreate logs in the Program class

Para escribir registros la clase Program, obtenga una instancia ILogger de inserción de dependencias:To write logs in the Program class, get an ILogger instance from DI:

public static void Main(string[] args)
{
    var host = CreateWebHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

No se admite directamente el registro durante la construcción del host.Logging during host construction isn't directly supported. Sin embargo, se puede usar un registrador independiente.However, a separate logger can be used. En el ejemplo siguiente, se usa un registrador Serilog para registrarse en CreateWebHostBuilder.In the following example, a Serilog logger is used to log in CreateWebHostBuilder. AddSerilog usa la configuración estática especificada en Log.Logger:AddSerilog uses the static configuration specified in Log.Logger:

using System;
using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Logging;

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var builtConfig = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .AddCommandLine(args)
            .Build();

        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .WriteTo.File(builtConfig["Logging:FilePath"])
            .CreateLogger();

        try
        {
            return WebHost.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddMvc();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {
                    logging.AddSerilog();
                })
                .UseStartup<Startup>();
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

            throw;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}

No hay métodos de registrador asincrónicosNo asynchronous logger methods

El registro debe ser tan rápido que no merezca la pena el costo de rendimiento del código asincrónico.Logging should be so fast that it isn't worth the performance cost of asynchronous code. Si el almacén de datos de registro es lento, no escriba directamente en él.If your logging data store is slow, don't write to it directly. Considere la posibilidad de escribir los mensajes de registro en un almacén rápido inicialmente y luego moverlos a la tienda lenta.Consider writing the log messages to a fast store initially, then move them to the slow store later. Por ejemplo, si inicia sesión en SQL Server, no desea hacerlo directamente en un método Log, ya que los métodos Log son sincrónicos.For example, if you're logging to SQL Server, you don't want to do that directly in a Log method, since the Log methods are synchronous. En su lugar, agregue sincrónicamente mensajes de registro a una cola en memoria y haga que un trabajo en segundo plano extraiga los mensajes de la cola para realizar el trabajo asincrónico de insertar datos en SQL Server.Instead, synchronously add log messages to an in-memory queue and have a background worker pull the messages out of the queue to do the asynchronous work of pushing data to SQL Server. Para obtener más información, vea este problema de GitHub.For more information, see this GitHub issue.

ConfiguraciónConfiguration

Uno o varios proveedores de configuración proporcionan la configuración del proveedor de registro:Logging provider configuration is provided by one or more configuration providers:

  • Formatos de archivo (INI, JSON y XML).File formats (INI, JSON, and XML).
  • Argumentos de la línea de comandos.Command-line arguments.
  • Variables de entorno.Environment variables.
  • Objetos de .NET en memoria.In-memory .NET objects.
  • El almacenamiento de administrador secreto sin cifrar.The unencrypted Secret Manager storage.
  • Un almacén de usuario cifrado, como Azure Key Vault.An encrypted user store, such as Azure Key Vault.
  • Proveedores personalizados (instalados o creados).Custom providers (installed or created).

Por ejemplo, la sección Logging de archivos de configuración de aplicación suele proporcionar la configuración de registro.For example, logging configuration is commonly provided by the Logging section of app settings files. En el ejemplo siguiente se muestra el contenido de un archivo appsettings.Development.json típico:The following example shows the contents of a typical appsettings.Development.json file:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    },
    "Console":
    {
      "IncludeScopes": true
    }
  }
}

La propiedad Logging puede tener LogLevel y propiedades del proveedor de registro (se muestra la consola).The Logging property can have LogLevel and log provider properties (Console is shown).

La propiedad LogLevel bajo Logging especifica el nivel mínimo que se va a registrar para las categorías seleccionadas.The LogLevel property under Logging specifies the minimum level to log for selected categories. En el ejemplo, las categorías System y Microsoft se registran en el nivel Information y todas las demás se registran en el nivel Debug.In the example, System and Microsoft categories log at Information level, and all others log at Debug level.

Otras propiedades bajo Logging especifican proveedores de registro.Other properties under Logging specify logging providers. El ejemplo es para el proveedor de consola.The example is for the Console provider. Si un proveedor admite ámbitos de registro, IncludeScopes indica si están habilitados.If a provider supports log scopes, IncludeScopes indicates whether they're enabled. Una propiedad de proveedor (como Console en el ejemplo) también puede especificar una propiedad LogLevel.A provider property (such as Console in the example) may also specify a LogLevel property. LogLevel en un proveedor especifica niveles de registro para ese proveedor.LogLevel under a provider specifies levels to log for that provider.

Si los niveles se especifican en Logging.{providername}.LogLevel, invalidan todo lo establecido en Logging.LogLevel.If levels are specified in Logging.{providername}.LogLevel, they override anything set in Logging.LogLevel.

La API de registro no incluye un escenario que permita cambiar los niveles de registro mientras se ejecuta una aplicación.The Logging API doesn't include a scenario to change log levels while an app is running. No obstante, algunos proveedores de configuración pueden volver a cargar la configuración, lo que tiene efecto inmediato en la configuración del registro.However, some configuration providers are capable of reloading configuration, which takes immediate effect on logging configuration. Por ejemplo, FileConfigurationProvider —agregado por CreateDefaultBuilder para leer los archivos de configuración— vuelve a cargar la configuración de registro de forma predeterminada.For example, the File Configuration Provider, which is added by CreateDefaultBuilder to read settings files, reloads logging configuration by default. Si se cambia la configuración en el código mientras se ejecuta una aplicación, la aplicación puede llamar a IConfigurationRoot.Reload para actualizar la configuración de registro de la aplicación.If configuration is changed in code while an app is running, the app can call IConfigurationRoot.Reload to update the app's logging configuration.

Para obtener información sobre cómo implementar proveedores de configuración, consulte Configuración en ASP.NET Core.For information on implementing configuration providers, see Configuración en ASP.NET Core.

Salida de registro de ejemploSample logging output

Con el código de ejemplo que se muestra en la sección anterior, los registros aparecen en la consola cuando la aplicación se ejecuta desde la línea de comandos.With the sample code shown in the preceding section, logs appear in the console when the app is run from the command line. Este es un ejemplo de salida de la consola:Here's an example of console output:

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 84.26180000000001ms 307
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/api/todo/0
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[3]
      Route matched with {action = "GetById", controller = "Todo", page = ""}. Executing controller action with signature Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller TodoApiSample.Controllers.TodoController (TodoApiSample).
info: TodoApiSample.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 42.9286ms
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 148.889ms 404

Los registros anteriores se generaron mediante la realización de una solicitud HTTP GET a la aplicación de ejemplo en http://localhost:5000/api/todo/0.The preceding logs were generated by making an HTTP Get request to the sample app at http://localhost:5000/api/todo/0.

Este es un ejemplo de los mismos registros tal y como aparecen en la ventana de depuración cuando se ejecuta la aplicación de ejemplo en Visual Studio:Here's an example of the same logs as they appear in the Debug window when you run the sample app in Visual Studio:

Microsoft.AspNetCore.Hosting.Diagnostics: Information: Request starting HTTP/2.0 GET https://localhost:44328/api/todo/0  
Microsoft.AspNetCore.Routing.EndpointMiddleware: Information: Executing endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker: Information: Route matched with {action = "GetById", controller = "Todo", page = ""}. Executing controller action with signature Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller TodoApiSample.Controllers.TodoController (TodoApiSample).
TodoApiSample.Controllers.TodoController: Information: Getting item 0
TodoApiSample.Controllers.TodoController: Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult: Information: Executing HttpStatusCodeResult, setting HTTP status code 404
Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker: Information: Executed action TodoApiSample.Controllers.TodoController.GetById (TodoApiSample) in 34.167ms
Microsoft.AspNetCore.Routing.EndpointMiddleware: Information: Executed endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
Microsoft.AspNetCore.Hosting.Diagnostics: Information: Request finished in 98.41300000000001ms 404

Los registros creados por las llamadas de ILogger se muestran en la sección anterior, empezando por “TodoApiSample”.The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApiSample". Los registros que comienzan por categorías de "Microsoft" son del código de marco de ASP.NET Core.The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core y el código de la aplicación usan la misma API y los mismos proveedores de registro.ASP.NET Core and application code are using the same logging API and providers.

Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request starting HTTP/1.1 GET http://localhost:53104/api/todo/0  
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
TodoApi.Controllers.TodoController:Information: Getting item 0
TodoApi.Controllers.TodoController:Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult:Information: Executing HttpStatusCodeResult, setting HTTP status code 404
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 152.5657ms
Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request finished in 316.3195ms 404

Los registros creados por las llamadas de ILogger se muestran en la sección anterior, empezando por “TodoApi”.The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApi". Los registros que comienzan por categorías de "Microsoft" son del código de marco de ASP.NET Core.The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. ASP.NET Core y el código de la aplicación usan la misma API y los mismos proveedores de registro.ASP.NET Core and application code are using the same logging API and providers.

En el resto de este artículo se explican algunos detalles y opciones para el registro.The remainder of this article explains some details and options for logging.

Paquetes NuGetNuGet packages

Las interfaces ILogger e ILoggerFactory se encuentran en Microsoft.Extensions.Logging.Abstractions, y sus implementaciones predeterminadas en Microsoft.Extensions.Logging.The ILogger and ILoggerFactory interfaces are in Microsoft.Extensions.Logging.Abstractions, and default implementations for them are in Microsoft.Extensions.Logging.

Categoría de registroLog category

Cuando se crea un objeto ILogger, se ha especificado una categoría para él.When an ILogger object is created, a category is specified for it. Esa categoría se incluye con cada mensaje de registro creado por esa instancia de ILogger.That category is included with each log message created by that instance of ILogger. La categoría puede ser cualquier cadena, pero la convención es usar el nombre de clase, como "TodoApi.Controllers.TodoController".The category may be any string, but the convention is to use the class name, such as "TodoApi.Controllers.TodoController".

Use ILogger<T> para obtener una instancia ILogger que utiliza el nombre de tipo completo de T como la categoría:Use ILogger<T> to get an ILogger instance that uses the fully qualified type name of T as the category:

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }
public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }

Para especificar explícitamente la categoría, llame a ILoggerFactory.CreateLogger:To explicitly specify the category, call ILoggerFactory.CreateLogger:

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILoggerFactory logger)
    {
        _todoRepository = todoRepository;
        _logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
    }
public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILoggerFactory logger)
    {
        _todoRepository = todoRepository;
        _logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
    }

ILogger<T> es equivale a llamar a CreateLogger con el nombre de tipo completo de T.ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

Nivel de registroLog level

Cara registro especifica un valor LogLevel.Every log specifies a LogLevel value. El nivel de registro indica la gravedad o importancia.The log level indicates the severity or importance. Por ejemplo, podría escribir un registro Information cuando un método termina con normalidad y un registro Warning cuando un método devuelve un código de estado 404 No encontrado.For example, you might write an Information log when a method ends normally and a Warning log when a method returns a 404 Not Found status code.

El siguiente código crea los registros Information y Warning:The following code creates Information and Warning logs:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

En el código anterior, el primer parámetro es el id. de evento del registro.In the preceding code, the first parameter is the Log event ID. El segundo parámetro es una plantilla de mensaje con marcadores de posición para los valores de argumento proporcionados por el resto de parámetros de método.The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. Los parámetros de método se explican detalladamente en la sección de la plantilla de mensaje más adelante en este artículo.The method parameters are explained in the message template section later in this article.

Los métodos de registro que incluyen el nivel en el nombre del método (por ejemplo LogInformation y LogWarning) son métodos de extensión para ILogger.Log methods that include the level in the method name (for example, LogInformation and LogWarning) are extension methods for ILogger. Estos métodos llaman a un método Log que toma un parámetro LogLevel.These methods call a Log method that takes a LogLevel parameter. Puede llamar directamente al método Log en lugar de a uno de estos métodos de extensión, pero la sintaxis es relativamente complicada.You can call the Log method directly rather than one of these extension methods, but the syntax is relatively complicated. Para más información, vea la ILogger y el código fuente de las extensiones de registrador.For more information, see ILogger and the logger extensions source code.

ASP.NET Core define los niveles de registro siguientes, que aquí se ordenan de menor a mayor gravedad.ASP.NET Core defines the following log levels, ordered here from lowest to highest severity.

  • Seguimiento = 0Trace = 0

    Para información que normalmente solo es útil para la depuración.For information that's typically valuable only for debugging. Estos mensajes pueden contener datos confidenciales de la aplicación, por lo que no deben habilitarse en un entorno de producción.These messages may contain sensitive application data and so shouldn't be enabled in a production environment. Deshabilitado de forma predeterminada.Disabled by default.

  • Depurar = 1Debug = 1

    Para información que puede ser útil para el desarrollo y la depuración.For information that may be useful in development and debugging. Ejemplo: Entering method Configure with flag set to true. Habilite los registros de nivel Debug en producción cuando esté solucionando un problema, debido al elevado volumen de registros.Example: Entering method Configure with flag set to true. Enable Debug level logs in production only when troubleshooting, due to the high volume of logs.

  • Información = 2Information = 2

    Para realizar el seguimiento del flujo general de la aplicación.For tracking the general flow of the app. Estos registros suelen tener algún valor a largo plazo.These logs typically have some long-term value. Ejemplo: Request received for path /api/todoExample: Request received for path /api/todo

  • Advertencia = 3Warning = 3

    Para los eventos anómalos o inesperados en el flujo de la aplicación.For abnormal or unexpected events in the app flow. Estos pueden incluir errores u otras condiciones que no hacen que la aplicación se detenga, pero que puede que sea necesario investigar.These may include errors or other conditions that don't cause the app to stop but might need to be investigated. Las excepciones controladas son un lugar común para usar el nivel de registro Warning.Handled exceptions are a common place to use the Warning log level. Ejemplo: FileNotFoundException for file quotes.txt.Example: FileNotFoundException for file quotes.txt.

  • Error = 4Error = 4

    Para los errores y excepciones que no se pueden controlar.For errors and exceptions that cannot be handled. Estos mensajes indican un error en la actividad u operación actual (por ejemplo, la solicitud HTTP actual), no un error de toda la aplicación.These messages indicate a failure in the current activity or operation (such as the current HTTP request), not an app-wide failure. Mensaje de registro de ejemplo: Cannot insert record due to duplicate key violation.Example log message: Cannot insert record due to duplicate key violation.

  • Crítico = 5Critical = 5

    Para los errores que requieren atención inmediata.For failures that require immediate attention. Ejemplos: escenarios de pérdida de datos, espacio en disco insuficiente.Examples: data loss scenarios, out of disk space.

Use el nivel de registro para controlar la cantidad de salida del registro que se escribe en un medio de almacenamiento determinado o ventana de presentación.Use the log level to control how much log output is written to a particular storage medium or display window. Por ejemplo:For example:

  • En producción:In production:
    • El registro en los niveles Trace a Information genera un gran volumen de mensajes de registro detallados.Logging at the Trace through Information levels produces a high-volume of detailed log messages. Para controlar los costos y no superar los límites de almacenamiento de datos, registre los mensajes de nivel Trace a Information en un almacén de datos de alto volumen y bajo costo.To control costs and not exceed data storage limits, log Trace through Information level messages to a high-volume, low-cost data store.
    • El registro en los niveles Warning a Critical normalmente produce menos mensajes de registro y de menor tamaño.Logging at Warning through Critical levels typically produces fewer, smaller log messages. Por lo tanto, los costos y los límites de almacenamiento no suelen ser un problema, lo que da lugar a una mayor flexibilidad a la hora de elegir el almacén de datos.Therefore, costs and storage limits usually aren't a concern, which results in greater flexibility of data store choice.
  • Durante el desarrollo:During development:
    • Registre los mensajes Warning a Critical en la consola.Log Warning through Critical messages to the console.
    • Agregue los mensajes Trace a Information al solucionar problemas.Add Trace through Information messages when troubleshooting.

En la sección Filtrado del registro de este artículo se explica cómo controlar los niveles de registro que controla un proveedor.The Log filtering section later in this article explains how to control which log levels a provider handles.

ASP.NET Core escribe registros de eventos de marco.ASP.NET Core writes logs for framework events. En los ejemplos de registro anteriores de este artículo se excluyeron los registros por debajo del nivel Information, por lo que no se crearon los registros de nivel Debug o Trace.The log examples earlier in this article excluded logs below Information level, so no Debug or Trace level logs were created. Este es un ejemplo de registros de consola generados mediante la ejecución de la aplicación de ejemplo configurada para mostrar registros Debug:Here's an example of console logs produced by running the sample app configured to show Debug logs:

info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[3]
      Route matched with {action = "GetById", controller = "Todo", page = ""}. Executing controller action with signature Microsoft.AspNetCore.Mvc.IActionResult GetById(System.String) on controller TodoApiSample.Controllers.TodoController (TodoApiSample).
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of authorization filters (in the following order): None
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of resource filters (in the following order): Microsoft.AspNetCore.Mvc.ViewFeatures.Filters.SaveTempDataFilter
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of action filters (in the following order): Microsoft.AspNetCore.Mvc.Filters.ControllerActionFilter (Order: -2147483648), Microsoft.AspNetCore.Mvc.ModelBinding.UnsupportedContentTypeFilter (Order: -3000)
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of exception filters (in the following order): None
dbug: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[1]
      Execution plan of result filters (in the following order): Microsoft.AspNetCore.Mvc.ViewFeatures.Filters.SaveTempDataFilter
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[22]
      Attempting to bind parameter 'id' of type 'System.String' ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder[44]
      Attempting to bind parameter 'id' of type 'System.String' using the name 'id' in request data ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder[45]
      Done attempting to bind parameter 'id' of type 'System.String'.
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[23]
      Done attempting to bind parameter 'id' of type 'System.String'.
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[26]
      Attempting to validate the bound parameter 'id' of type 'System.String' ...
dbug: Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder[27]
      Done attempting to validate the bound parameter 'id' of type 'System.String'.
info: TodoApiSample.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Infrastructure.ControllerActionInvoker[2]
      Executed action TodoApiSample.Controllers.TodoController.GetById (TodoApiSample) in 32.690400000000004ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint 'TodoApiSample.Controllers.TodoController.GetById (TodoApiSample)'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 176.9103ms 404
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:62555/api/todo/0
dbug: Microsoft.AspNetCore.Routing.Tree.TreeRouter[1]
      Request successfully matched the route with name 'GetTodo' and template 'api/Todo/{id}'.
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Update (TodoApi)' with id '089d59b6-92ec-472d-b552-cc613dfd625d' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Delete (TodoApi)' with id 'f3476abe-4bd9-4ad3-9261-3ead09607366' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action TodoApi.Controllers.TodoController.GetById (TodoApi)
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action method TodoApi.Controllers.TodoController.GetById (TodoApi), returned result Microsoft.AspNetCore.Mvc.NotFoundResult.
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 0.8788ms
dbug: Microsoft.AspNetCore.Server.Kestrel[9]
      Connection id "0HL6L7NEFF2QD" completed keep alive response.
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 2.7286ms 404

Id. de evento del registroLog event ID

Cada registro se puede especificar un id. de evento.Each log can specify an event ID. La aplicación de ejemplo lo hace mediante una clase LoggingEvents definida de forma local:The sample app does this by using a locally defined LoggingEvents class:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public class LoggingEvents
{
    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 GetItemNotFound = 4000;
    public const int UpdateItemNotFound = 4001;
}
public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public class LoggingEvents
{
    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 GetItemNotFound = 4000;
    public const int UpdateItemNotFound = 4001;
}

Un id. de evento asocia un conjunto de eventos.An event ID associates a set of events. Por ejemplo, todos los registros relacionados con la presentación de una lista de elementos en una página podrían ser 1001.For example, all logs related to displaying a list of items on a page might be 1001.

El proveedor de registro puede almacenar el id. de evento en un campo de identificador, en el mensaje de registro o no almacenarlo.The logging provider may store the event ID in an ID field, in the logging message, or not at all. El proveedor de depuración no muestra los identificadores de evento.The Debug provider doesn't show event IDs. El proveedor de consola muestra los identificadores de evento entre corchetes después de la categoría:The console provider shows event IDs in brackets after the category:

info: TodoApi.Controllers.TodoController[1002]
      Getting item invalidid
warn: TodoApi.Controllers.TodoController[4000]
      GetById(invalidid) NOT FOUND

Plantilla de mensaje de registroLog message template

Cada registro especifica una plantilla de mensaje.Each log specifies a message template. La plantilla de mensaje puede contener marcadores de posición para los que se proporcionan argumentos.The message template can contain placeholders for which arguments are provided. Use los nombres de los marcadores de posición, no números.Use names for the placeholders, not numbers.

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

El orden de los marcadores de posición, no sus nombres, determina qué parámetros se usan para proporcionar sus valores.The order of placeholders, not their names, determines which parameters are used to provide their values. En el código siguiente, tenga en cuenta que los nombres de parámetro están fuera de la secuencia en la plantilla de mensaje:In the following code, notice that the parameter names are out of sequence in the message template:

string p1 = "parm1";
string p2 = "parm2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

Este código crea un mensaje de registro con los valores de parámetro en secuencia:This code creates a log message with the parameter values in sequence:

Parameter values: parm1, parm2

La plataforma de registro funciona de esta manera para que los proveedores de registro puedan implementar el registro semántico, también conocido como registro estructurado.The logging framework works this way so that logging providers can implement semantic logging, also known as structured logging. Los propios argumentos se pasan al sistema de registro, no solo a la plantilla de mensaje con formato.The arguments themselves are passed to the logging system, not just the formatted message template. Esta información permite a los proveedores de registro almacenar los valores de parámetro como campos.This information enables logging providers to store the parameter values as fields. Por ejemplo, suponga que las llamadas del método del registrador tiene el aspecto siguiente:For example, suppose logger method calls look like this:

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

Si envía los registros a Azure Table Storage, cada entidad de Azure Table puede tener propiedades ID y RequestTime, lo que simplifica las consultas en los datos de registro.If you're sending the logs to Azure Table Storage, each Azure Table entity can have ID and RequestTime properties, which simplifies queries on log data. Una consulta puede buscar todos los registros dentro de un intervalo RequestTime determinado sin analizar el tiempo de espera del mensaje de texto.A query can find all logs within a particular RequestTime range without parsing the time out of the text message.

Excepciones de registroLogging exceptions

Los métodos de registrador tienen sobrecargas que le permiten pasar una excepción, como en el ejemplo siguiente:The logger methods have overloads that let you pass in an exception, as in the following example:

catch (Exception ex)
{
    _logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({Id}) NOT FOUND", id);
    return NotFound();
}
return new ObjectResult(item);
catch (Exception ex)
{
    _logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({Id}) NOT FOUND", id);
    return NotFound();
}
return new ObjectResult(item);

Cada proveedor controla la información de la excepción de maneras diferentes.Different providers handle the exception information in different ways. Este es un ejemplo de salida del proveedor de depuración del código mostrado anteriormente.Here's an example of Debug provider output from the code shown above.

TodoApiSample.Controllers.TodoController: Warning: GetById(55) NOT FOUND

System.Exception: Item not found exception.
   at TodoApiSample.Controllers.TodoController.GetById(String id) in C:\TodoApiSample\Controllers\TodoController.cs:line 226

Filtrado del registroLog filtering

Puede especificar un nivel de registro mínimo para un proveedor y una categoría específicos, o para todos los proveedores o todas las categorías.You can specify a minimum log level for a specific provider and category or for all providers or all categories. Los registros por debajo del nivel mínimo no se pasan a ese proveedor, de modo que no se muestran o almacenan.Any logs below the minimum level aren't passed to that provider, so they don't get displayed or stored.

Para suprimir todos los registros, especifique LogLevel.None como el nivel de registro mínimo.To suppress all logs, specify LogLevel.None as the minimum log level. El valor entero de LogLevel.None es 6, que es superior a LogLevel.Critical (5).The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

Creación de reglas de filtro en la configuraciónCreate filter rules in configuration

El código de la plantilla de proyecto llama a CreateDefaultBuilder para configurar el registro para los proveedores de Console, Debug y EventSource (ASP.NET Core 2.2 o versiones posteriores).The project template code calls CreateDefaultBuilder to set up logging for the Console, Debug, and EventSource (ASP.NET Core 2.2 or later) providers. El método CreateDefaultBuilder configura el registro para buscar la configuración en una sección de Logging, como se explica anteriormente en este artículo.The CreateDefaultBuilder method sets up logging to look for configuration in a Logging section, as explained earlier in this article.

Los datos de configuración especifican niveles de registro mínimo por proveedor y categoría, como en el ejemplo siguiente:The configuration data specifies minimum log levels by provider and category, as in the following example:

{
  "Logging": {
    "Debug": {
      "LogLevel": {
        "Default": "Information"
      }
    },
    "Console": {
      "IncludeScopes": false,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "LogLevel": {
      "Default": "Debug"
    }
  }
}
{
  "Logging": {
    "Debug": {
      "LogLevel": {
        "Default": "Information"
      }
    },
    "Console": {
      "IncludeScopes": false,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

Este archivo JSON crea seis reglas de filtro, una para el proveedor de depuración, cuatro para el proveedor de la consola y una para todos los proveedores.This JSON creates six filter rules: one for the Debug provider, four for the Console provider, and one for all providers. Se elige una sola regla para cada proveedor cuando se crea un objeto ILogger.A single rule is chosen for each provider when an ILogger object is created.

Reglas de filtro en el códigoFilter rules in code

En el siguiente ejemplo se muestra cómo registrar reglas de filtro en el código:The following example shows how to register filter rules in code:

.ConfigureLogging(logging =>
    logging.AddFilter("System", LogLevel.Debug)
           .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace))
WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging =>
        logging.AddFilter("System", LogLevel.Debug)
               .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace));

El segundo AddFilter especifica el proveedor de depuración mediante su nombre de tipo.The second AddFilter specifies the Debug provider by using its type name. El primer AddFilter se aplica a todos los proveedores, dado que no especifica un tipo de proveedor.The first AddFilter applies to all providers because it doesn't specify a provider type.

Cómo se aplican las reglas de filtroHow filtering rules are applied

Los datos de configuración y el código de AddFilter que se muestran en los ejemplos anteriores crean las reglas que se muestran en la tabla siguiente.The configuration data and the AddFilter code shown in the preceding examples create the rules shown in the following table. Las seis primeras proceden del ejemplo de configuración y las dos últimas del ejemplo de código.The first six come from the configuration example and the last two come from the code example.

númeroNumber ProveedorProvider Categorías que comienzan por...Categories that begin with ... Nivel de registro mínimoMinimum log level
11 DepuraciónDebug Todas las categoríasAll categories InformaciónInformation
22 ConsolaConsole Microsoft.AspNetCore.Mvc.Razor.InternalMicrosoft.AspNetCore.Mvc.Razor.Internal AdvertenciaWarning
33 ConsolaConsole Microsoft.AspNetCore.Mvc.Razor.RazorMicrosoft.AspNetCore.Mvc.Razor.Razor DepuraciónDebug
44 ConsolaConsole Microsoft.AspNetCore.Mvc.RazorMicrosoft.AspNetCore.Mvc.Razor ErrorError
55 ConsolaConsole Todas las categoríasAll categories InformaciónInformation
66 Todos los proveedoresAll providers Todas las categoríasAll categories DepuraciónDebug
77 Todos los proveedoresAll providers SistemaSystem DepuraciónDebug
88 DepuraciónDebug MicrosoftMicrosoft SeguimientoTrace

Cuando se crea un objeto ILogger, el objeto ILoggerFactory selecciona una sola regla por proveedor para aplicar a ese registrador.When an ILogger object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. Todos los mensajes escritos por una instancia ILogger se filtran según las reglas seleccionadas.All messages written by an ILogger instance are filtered based on the selected rules. De las reglas disponibles se selecciona la más específica posible para cada par de categoría y proveedor.The most specific rule possible for each provider and category pair is selected from the available rules.

Cuando se crea un ILogger para una categoría determinada, se usa el algoritmo siguiente para cada proveedor:The following algorithm is used for each provider when an ILogger is created for a given category:

  • Se seleccionan todas las reglas que coinciden con el proveedor o su alias.Select all rules that match the provider or its alias. Si no se encuentra ninguna coincidencia, se seleccionan todas las reglas con un proveedor vacío.If no match is found, select all rules with an empty provider.
  • Del resultado del paso anterior, se seleccionan las reglas con el prefijo de categoría coincidente más largo.From the result of the preceding step, select rules with longest matching category prefix. Si no se encuentra ninguna coincidencia, se seleccionan todas las reglas que no especifican una categoría.If no match is found, select all rules that don't specify a category.
  • Si se seleccionan varias reglas, se toma la última.If multiple rules are selected, take the last one.
  • Si no se selecciona ninguna regla, se usa MinimumLevel.If no rules are selected, use MinimumLevel.

Con la lista de reglas anterior, supongamos que crea un objeto ILogger para la categoría "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":With the preceding list of rules, suppose you create an ILogger object for category "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":

  • Para el proveedor de depuración, se aplican las reglas 1, 6 y 8.For the Debug provider, rules 1, 6, and 8 apply. La regla 8 es la más específica, por lo que se selecciona.Rule 8 is most specific, so that's the one selected.
  • Para el proveedor de la consola, se aplican las reglas 3, 4, 5 y 6.For the Console provider, rules 3, 4, 5, and 6 apply. La regla 3 es la más específica.Rule 3 is most specific.

La instancia ILogger resultante envía los registros de nivel Trace y superiores al proveedor de depuración.The resulting ILogger instance sends logs of Trace level and above to the Debug provider. Los registros de nivel Debug y superiores se envían al proveedor de consola.Logs of Debug level and above are sent to the Console provider.

Alias de proveedorProvider aliases

Cada proveedor define un alias que se puede utilizar en la configuración en lugar del nombre de tipo completo.Each provider defines an alias that can be used in configuration in place of the fully qualified type name. Para los proveedores integrados, use los alias siguientes:For the built-in providers, use the following aliases:

  • ConsolaConsole
  • DepuraciónDebug
  • EventSourceEventSource
  • EventLogEventLog
  • TraceSourceTraceSource
  • AzureAppServicesFileAzureAppServicesFile
  • AzureAppServicesBlobAzureAppServicesBlob
  • ApplicationInsightsApplicationInsights

Nivel mínimo predeterminadoDefault minimum level

Hay una configuración de nivel mínimo que solo tiene efecto si no se aplica ninguna regla de configuración o código para un proveedor y una categoría determinados.There's a minimum level setting that takes effect only if no rules from configuration or code apply for a given provider and category. En el ejemplo siguiente se muestra cómo establecer el nivel mínimo:The following example shows how to set the minimum level:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning));

Si no establece explícitamente el nivel mínimo, el valor predeterminado es Information, lo que significa que los registros Trace y Debug se omiten.If you don't explicitly set the minimum level, the default value is Information, which means that Trace and Debug logs are ignored.

Funciones de filtroFilter functions

Se invoca una función de filtro para todos los proveedores y categorías que no tienen reglas asignadas mediante configuración o código.A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code. El código de la función tiene acceso al tipo de proveedor, la categoría y el nivel de registro.Code in the function has access to the provider type, category, and log level. Por ejemplo:For example:

.ConfigureLogging(logBuilder =>
{
    logBuilder.AddFilter((provider, category, logLevel) =>
    {
        if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
            category == "TodoApiSample.Controllers.TodoController")
        {
            return false;
        }
        return true;
    });
})
WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logBuilder =>
    {
        logBuilder.AddFilter((provider, category, logLevel) =>
        {
            if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
                category == "TodoApiSample.Controllers.TodoController")
            {
                return false;
            }
            return true;
        });
    });

Niveles y categorías del sistemaSystem categories and levels

Estas son algunas categorías que ASP.NET Core y Entity Framework Core usan, con notas sobre lo que los registros de espera de ellas:Here are some categories used by ASP.NET Core and Entity Framework Core, with notes about what logs to expect from them:

CategoríaCategory NotasNotes
Microsoft.AspNetCoreMicrosoft.AspNetCore Diagnósticos generales de ASP.NET Core.General ASP.NET Core diagnostics.
Microsoft.AspNetCore.DataProtectionMicrosoft.AspNetCore.DataProtection Qué claves se tuvieron en cuenta, encontraron y usaron.Which keys were considered, found, and used.
Microsoft.AspNetCore.HostFilteringMicrosoft.AspNetCore.HostFiltering Hosts permitidos.Hosts allowed.
Microsoft.AspNetCore.HostingMicrosoft.AspNetCore.Hosting Cuánto tiempo tardaron en completarse las solicitudes HTTP y a qué hora comenzaron.How long HTTP requests took to complete and what time they started. Qué ensamblados de inicio de hospedaje se cargaron.Which hosting startup assemblies were loaded.
Microsoft.AspNetCore.MvcMicrosoft.AspNetCore.Mvc Diagnósticos de MVC y Razor.MVC and Razor diagnostics. Enlace de modelos, ejecución de filtros, compilación de vistas y selección de acciones.Model binding, filter execution, view compilation, action selection.
Microsoft.AspNetCore.RoutingMicrosoft.AspNetCore.Routing Información de coincidencia de ruta.Route matching information.
Microsoft.AspNetCore.ServerMicrosoft.AspNetCore.Server Inicio y detención de conexión y mantener las respuestas activas.Connection start, stop, and keep alive responses. Información de certificado HTTPS.HTTPS certificate information.
Microsoft.AspNetCore.StaticFilesMicrosoft.AspNetCore.StaticFiles Archivos servidos.Files served.
Microsoft.EntityFrameworkCoreMicrosoft.EntityFrameworkCore Diagnósticos generales de Entity Framework Core.General Entity Framework Core diagnostics. Actividad y la configuración de bases de datos, detección de cambios y migraciones.Database activity and configuration, change detection, migrations.

Ámbitos de registroLog scopes

Un ámbito puede agrupar un conjunto de operaciones lógicas.A scope can group a set of logical operations. Esta agrupación se puede utilizar para adjuntar los mismos datos para cada registro que se crea como parte de un conjunto.This grouping can be used to attach the same data to each log that's created as part of a set. Por ejemplo, cada registro creado como parte del procesamiento de una transacción puede incluir el identificador de dicha transacción.For example, every log created as part of processing a transaction can include the transaction ID.

Un ámbito es un tipo IDisposable devuelto por el método BeginScope y se conserva hasta que se elimina.A scope is an IDisposable type that's returned by the BeginScope method and lasts until it's disposed. Use un ámbito encapsulando las llamadas de registrador en un bloque using:Use a scope by wrapping logger calls in a using block:

public IActionResult GetById(string id)
{
    TodoItem item;
    using (_logger.BeginScope("Message attached to logs created in the using block"))
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        item = _todoRepository.Find(id);
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
    }
    return new ObjectResult(item);
}
public IActionResult GetById(string id)
{
    TodoItem item;
    using (_logger.BeginScope("Message attached to logs created in the using block"))
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        item = _todoRepository.Find(id);
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
    }
    return new ObjectResult(item);
}

El código siguiente permite ámbitos para el proveedor de la consola:The following code enables scopes for the console provider:

Program.cs:Program.cs:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.ClearProviders();
            logging.AddConsole(options => options.IncludeScopes = true);
            logging.AddDebug();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });
.ConfigureLogging((hostingContext, logging) =>
{
    logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
    logging.AddConsole(options => options.IncludeScopes = true);
    logging.AddDebug();
})

Nota

Es necesario configurar la opción del registrador de consola IncludeScopes para habilitar el registro basado en el ámbito.Configuring the IncludeScopes console logger option is required to enable scope-based logging.

Para obtener información sobre la configuración, consulte la sección Configuración.For information on configuration, see the Configuration section.

Cada mensaje de registro incluye la información de ámbito:Each log message includes the scoped information:

info: TodoApiSample.Controllers.TodoController[1002]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      Getting item 0
warn: TodoApiSample.Controllers.TodoController[4000]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApiSample.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      GetById(0) NOT FOUND

Proveedores de registro integradosBuilt-in logging providers

ASP.NET Core incluye los proveedores siguientes:ASP.NET Core ships the following providers:

Para obtener información sobre stdout y el registro de depuración con el módulo ASP.NET Core, consulte Solucionar problemas de ASP.NET Core en Azure App Service e IIS y Módulo ASP.NET Core.For information on stdout and debug logging with the ASP.NET Core Module, see Solucionar problemas de ASP.NET Core en Azure App Service e IIS and Módulo ASP.NET Core.

Proveedor de la consolaConsole provider

El paquete de proveedor Microsoft.Extensions.Logging.Console envía la salida del registro a la consola.The Microsoft.Extensions.Logging.Console provider package sends log output to the console.

logging.AddConsole();

Para ver una salida de registro de la consola, abra un símbolo del sistema en la carpeta del proyecto y ejecute este comando:To see console logging output, open a command prompt in the project folder and run the following command:

dotnet run

Proveedor de depuraciónDebug provider

El paquete de proveedor Microsoft.Extensions.Logging.Debug escribe la salida del registro mediante la clase System.Diagnostics.Debug (llamadas a métodos Debug.WriteLine).The Microsoft.Extensions.Logging.Debug provider package writes log output by using the System.Diagnostics.Debug class (Debug.WriteLine method calls).

En Linux, este proveedor escribe registros en /var/log/message.On Linux, this provider writes logs to /var/log/message.

logging.AddDebug();

Proveedor de origen del eventoEvent Source provider

El paquete del proveedor Microsoft.Extensions.Logging.EventSource escribe en una multiplataforma de origen del evento con el nombre Microsoft-Extensions-Logging.The Microsoft.Extensions.Logging.EventSource provider package writes to an Event Source cross-platform with the name Microsoft-Extensions-Logging. En Windows, el proveedor utiliza ETW.On Windows, the provider uses ETW.

logging.AddEventSourceLogger();

El proveedor de origen del evento se agrega automáticamente cuando se llama a CreateDefaultBuilder para compilar el host.The Event Source provider is added automatically when CreateDefaultBuilder is called to build the host.

herramienta de seguimiento de dotnetdotnet trace tooling

La herramienta de seguimiento de dotnet es una herramienta global de CLI multiplataforma que permite la recopilación de seguimientos de .NET Core de un proceso en ejecución.The dotnet-trace tool is a cross-platform CLI global tool that enables the collection of .NET Core traces of a running process. La herramienta recopila datos del proveedor Microsoft.Extensions.Logging.EventSource mediante un LoggingEventSource.The tool collects Microsoft.Extensions.Logging.EventSource provider data using a LoggingEventSource.

Instale la herramienta de seguimiento de dotnet con el siguiente comando:Install the dotnet trace tooling with the following command:

dotnet tool install --global dotnet-trace

Use la herramienta de seguimiento de dotnet para recopilar un seguimiento de una aplicación:Use the dotnet trace tooling to collect a trace from an app:

  1. Si la aplicación no compila el host con CreateDefaultBuilder, agregue el proveedor de origen del evento a la configuración de registro de la aplicación.If the app doesn't build the host with CreateDefaultBuilder, add the Event Source provider to the app's logging configuration.

  2. Ejecute la aplicación con el comando dotnet run.Run the app with the dotnet run command.

  3. Determine el identificador del proceso (PID) de la aplicación .NET Core:Determine the process identifier (PID) of the .NET Core app:

    Busque el PID del proceso que tenga el mismo nombre que el ensamblado de la aplicación.Find the PID for the process that has the same name as the app's assembly.

  4. Ejecute el comando dotnet trace.Execute the dotnet trace command.

    Sintaxis general del comando:General command syntax:

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

    Al usar un shell de comandos de PowerShell, incluya el valor --providers entre comillas simples ('):When using a PowerShell command shell, enclose the --providers value in single quotes ('):

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

    En plataformas que no sean Windows, agregue la opción -f speedscope para cambiar el formato del archivo de seguimiento de salida a speedscope.On non-Windows platforms, add the -f speedscope option to change the format of the output trace file to speedscope.

    Palabra claveKeyword DescripciónDescription
    11 Registre los eventos meta sobre el elemento LoggingEventSource.Log meta events about the LoggingEventSource. No registre eventos de ILogger).Doesn't log events from ILogger).
    22 Activa el evento Message cuando se llama a ILogger.Log().Turns on the Message event when ILogger.Log() is called. Proporciona la información mediante programación (sin formato).Provides information in a programmatic (not formatted) way.
    44 Activa el evento FormatMessage cuando se llama a ILogger.Log().Turns on the FormatMessage event when ILogger.Log() is called. Proporciona la versión de cadena con formato de la información.Provides the formatted string version of the information.
    88 Activa el evento MessageJson cuando se llama a ILogger.Log().Turns on the MessageJson event when ILogger.Log() is called. Proporciona una representación JSON de los argumentos.Provides a JSON representation of the arguments.
    Nivel de eventoEvent Level DescripciónDescription
    00 LogAlways
    11 Critical
    22 Error
    33 Warning
    44 Informational
    55 Verbose

    Las entradas FilterSpecs de {Logger Category} y {Event Level} representan condiciones de filtrado de registros adicionales.FilterSpecs entries for {Logger Category} and {Event Level} represent additional log filtering conditions. Separe las entradas FilterSpecs con un punto y coma (;).Separate FilterSpecs entries with a semicolon (;).

    Ejemplo de uso de un shell de comandos de Windows (no hay comillas simples alrededor del valor --providers):Example using a Windows command shell (no single quotes around the --providers value):

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

    El comando anterior activa lo siguiente:The preceding command activates:

    • Registrador de origen del evento para generar cadenas con formato (4) de los errores (2).The Event Source logger to produce formatted strings (4) for errors (2).
    • Registro Microsoft.AspNetCore.Hosting en el nivel de registro Informational (4).Microsoft.AspNetCore.Hosting logging at the Informational logging level (4).
  5. Presione la tecla Entrar o Ctrl + C para detener las herramientas de seguimiento de dotnet.Stop the dotnet trace tooling by pressing the Enter key or Ctrl+C.

    El seguimiento se guarda con el nombre trace.nettrace en la carpeta en la que se ejecuta el comando dotnet trace.The trace is saved with the name trace.nettrace in the folder where the dotnet trace command is executed.

  6. Abra el seguimiento con Perfview.Open the trace with Perfview. Abra el archivo trace.nettrace y explore los eventos de seguimiento.Open the trace.nettrace file and explore the trace events.

Para obtener más información, consulte:For more information, see:

PerfviewPerfview

Use la utilidad PerfView para recopilar y ver los registros.Use the PerfView utility to collect and view logs. Hay otras herramientas para ver los registros ETW, pero PerfView proporciona la mejor experiencia para trabajar con los eventos ETW emitidos por ASP.NET Core.There are other tools for viewing ETW logs, but PerfView provides the best experience for working with the ETW events emitted by ASP.NET Core.

Para configurar PerfView para la recopilación de eventos registrados por este proveedor, agregue la cadena *Microsoft-Extensions-Logging a la lista Proveedores adicionales.To configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. (No olvide el asterisco al principio de la cadena).(Don't miss the asterisk at the start of the string.)

Proveedores adicionales de Perfview

Proveedor EventLog de WindowsWindows EventLog provider

El paquete de proveedor Microsoft.Extensions.Logging.EventLog envía la salida del registro al Registro de eventos de Windows.The Microsoft.Extensions.Logging.EventLog provider package sends log output to the Windows Event Log.

logging.AddEventLog();

Las sobrecargas de AddEventLog permiten pasar EventLogSettings.AddEventLog overloads let you pass in EventLogSettings. Si es null o no se especifica, se usa la siguiente configuración predeterminada:If null or not specified, the following default settings are used:

  • LogName: "Aplicación"LogName – "Application"
  • SourceName: "Entorno de ejecución .NET"SourceName – ".NET Runtime"
  • MachineName: equipo localMachineName – local machine

Los eventos se registran para el Nivel de advertencia y superior.Events are logged for Warning level and higher. Para registrar eventos inferiores a Warning, establezca el nivel de registro de forma explícita.To log events lower than Warning, explicitly set the log level. Por ejemplo, agregue lo siguiente al archivo appsettings.json:For example, add the following to the appsettings.json file:

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

Proveedor TraceSourceTraceSource provider

El paquete de proveedor Microsoft.Extensions.Logging.TraceSource usa las bibliotecas y proveedores de TraceSource.The Microsoft.Extensions.Logging.TraceSource provider package uses the TraceSource libraries and providers.

logging.AddTraceSource(sourceSwitchName);

Las sobrecargas de AddTraceSource permiten pasar un modificador de origen y un agente de escucha de seguimiento.AddTraceSource overloads let you pass in a source switch and a trace listener.

Para usar este proveedor, una aplicación debe ejecutarse en .NET Framework (en lugar de .NET Core).To use this provider, an app has to run on the .NET Framework (rather than .NET Core). El proveedor puede enrutar mensajes a una variedad de agentes de escucha, como TextWriterTraceListener que se usa en la aplicación de ejemplo.The provider can route messages to a variety of listeners, such as the TextWriterTraceListener used in the sample app.

Proveedor Azure App ServiceAzure App Service provider

El paquete de proveedor Microsoft.Extensions.Logging.AzureAppServices escribe los registros en archivos de texto en el sistema de archivos de una aplicación de Azure App Service y en Blob Storage en una cuenta de Azure Storage.The Microsoft.Extensions.Logging.AzureAppServices provider package writes logs to text files in an Azure App Service app's file system and to blob storage in an Azure Storage account.

logging.AddAzureWebAppDiagnostics();

El paquete del proveedor no se incluye en el marco compartido.The provider package isn't included in the shared framework. Para usar el proveedor, agregue el paquete del proveedor al proyecto.To use the provider, add the provider package to the project.

El paquete de proveedor no está incluido en el metapaquete Microsoft.AspNetCore.App.The provider package isn't included in the Microsoft.AspNetCore.App metapackage. Si el destino es .NET Framework o hace referencia al metapaquete Microsoft.AspNetCore.App, agregue el paquete del proveedor al proyecto.When targeting .NET Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider package to the project.

Para configurar las opciones de proveedor, use AzureFileLoggerOptions y AzureBlobLoggerOptions, tal y como se muestra en el ejemplo siguiente:To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the following example:

public static void Main(string[] args)
{
    var host = CreateHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
            .ConfigureServices(serviceCollection => serviceCollection
                .Configure<AzureFileLoggerOptions>(options =>
                {
                    options.FileName = "azure-diagnostics-";
                    options.FileSizeLimit = 50 * 1024;
                    options.RetainedFileCountLimit = 5;
                }).Configure<AzureBlobLoggerOptions>(options =>
                {
                    options.BlobName = "log.txt";
                })
            )
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Para configurar las opciones de proveedor, use AzureFileLoggerOptions y AzureBlobLoggerOptions, tal y como se muestra en el ejemplo siguiente:To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the following example:

public static void Main(string[] args)
{
    var host = CreateWebHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
        .ConfigureServices(serviceCollection => serviceCollection
                .Configure<AzureFileLoggerOptions>(options =>
                {
                    options.FileName = "azure-diagnostics-";
                    options.FileSizeLimit = 50 * 1024;
                    options.RetainedFileCountLimit = 5;
                }).Configure<AzureBlobLoggerOptions>(options =>
                {
                    options.BlobName = "log.txt";
                }))
        .UseStartup<Startup>();

Una sobrecarga AddAzureWebAppDiagnostics permite pasar AzureAppServicesDiagnosticsSettings.An AddAzureWebAppDiagnostics overload lets you pass in AzureAppServicesDiagnosticsSettings. El objeto de configuración puede invalidar la configuración predeterminada, como la plantilla de salida de registro, el nombre de blob y el límite de tamaño de archivo.The settings object can override default settings, such as the logging output template, blob name, and file size limit. (La plantilla salida es una plantilla de mensaje que se aplica a todos los registros además de que se proporciona con una llamada de método ILogger).(Output template is a message template that's applied to all logs in addition to what's provided with an ILogger method call.)

Al realizar una implementación en una aplicación de App Service, esta respeta la configuración de la sección Registros de App Service de la página App Service de Azure Portal.When you deploy to an App Service app, the application honors the settings in the App Service logs section of the App Service page of the Azure portal. Cuando se actualiza la configuración siguiente, los cambios se aplican de inmediato sin necesidad de reiniciar ni de volver a implementar la aplicación.When the following settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

  • Registro de la aplicación (sistema de archivos)Application Logging (Filesystem)
  • Registro de la aplicación (blob)Application Logging (Blob)

La ubicación predeterminada de los archivos de registro es la carpeta D:\home\LogFiles\Application y el nombre de archivo predeterminado es diagnostics-aaaammdd.txt.The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. El límite de tamaño de archivo predeterminado es 10 MB, y el número máximo predeterminado de archivos que se conservan es 2.The default file size limit is 10 MB, and the default maximum number of files retained is 2. El nombre de blob predeterminado es {nombre-de-la-aplicación}{marca de tiempo}/aaaa/mm/dd/hh/{guid}-applicationLog.txt.The default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

El proveedor solo funciona cuando el proyecto se ejecuta en el entorno de Azure.The provider only works when the project runs in the Azure environment. No tiene ningún efecto cuando el proyecto se ejecuta de manera local (no escribe en los archivos locales ni en el almacenamiento de desarrollo local de blobs).It has no effect when the project is run locally—it doesn't write to local files or local development storage for blobs.

Secuencias de registro de AzureAzure log streaming

Las secuencias de registro de Azure permiten ver la actividad de registro en tiempo real desde:Azure log streaming lets you view log activity in real time from:

  • El servidor de aplicacionesThe app server
  • El servidor webThe web server
  • Error del seguimiento de solicitudesFailed request tracing

Para configurar las secuencias de registro de Azure:To configure Azure log streaming:

  • Navegue hasta la página Registros de App Service desde la página de portal de la aplicación.Navigate to the App Service logs page from your app's portal page.
  • Establezca Registro de la aplicación (sistema de archivos) en Activado.Set Application Logging (Filesystem) to On.
  • Elija el Nivel de registro.Choose the log Level. Este valor solo se aplica a las secuencias de registro de Azure, no a otros proveedores de registro de la aplicación.This setting only applies to Azure log streaming, not other logging providers in the app.

Navegue hasta la página Secuencia de registro para consultar los mensajes de la aplicación.Navigate to the Log Stream page to view app messages. La aplicación los registra a través de la interfaz ILogger.They're logged by the app through the ILogger interface.

Registro de seguimiento de Azure Application InsightsAzure Application Insights trace logging

El proveedor de paquete Microsoft.Extensions.Logging.ApplicationInsights escribe los registros en Azure Application Insights.The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. Application Insights es un servicio que supervisa una aplicación web y proporciona herramientas para consultar y analizar los datos de telemetría.Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. Si usa este proveedor, puede consultar y analizar los registros mediante las herramientas de Application Insights.If you use this provider, you can query and analyze your logs by using the Application Insights tools.

El proveedor de registro se incluye como dependencia de Microsoft.ApplicationInsights.AspNetCore, que es el paquete que proporciona toda la telemetría disponible para ASP.NET Core.The logging provider is included as a dependency of Microsoft.ApplicationInsights.AspNetCore, which is the package that provides all available telemetry for ASP.NET Core. Si usa este paquete, no tiene que instalar el proveedor de paquete.If you use this package, you don't have to install the provider package.

No use el paquete Microsoft.ApplicationInsights.Web—que es para ASP.NET 4.x.Don't use the Microsoft.ApplicationInsights.Web package—that's for ASP.NET 4.x.

Para obtener más información, vea los siguientes recursos:For more information, see the following resources:

Proveedores de registro de tercerosThird-party logging providers

Plataformas de registro de terceros que funcionan con ASP.NET Core:Third-party logging frameworks that work with ASP.NET Core:

Algunas plataformas de terceros pueden realizar registro semántico, también conocido como registro estructurado.Some third-party frameworks can perform semantic logging, also known as structured logging.

El uso de una plataforma de terceros es similar al uso de uno de los proveedores integrados:Using a third-party framework is similar to using one of the built-in providers:

  1. Agregue un paquete NuGet al proyecto.Add a NuGet package to your project.
  2. Llame a un método de extensión ILoggerFactory proporcionado por el marco de registro.Call an ILoggerFactory extension method provided by the logging framework.

Para más información, vea la documentación de cada proveedor.For more information, see each provider's documentation. Microsoft no admite los proveedores de registro de terceros.Third-party logging providers aren't supported by Microsoft.

Recursos adicionalesAdditional resources