Custom/logger (#18258)

* Add custom logger documentaions (#11842)

* Add a section in the docs aspnetcore/fundamentals/logging/index.md
* Add a sample at aspnetcore/fundamentals/logging/loggermessage/samples/3.1/CustomLogger

* Custom loggiing

* Custom loggiing

* Custom loggiing

* Custom loggiing

* Custom loggiing

* Custom loggiing

* Apply suggestions from code review

Co-authored-by: Brennan <brecon@microsoft.com>

* react to feedback

* react to feedback

* react to feedback

Co-authored-by: Juergen Gutsch <juergen@gutsch-online.de>
Co-authored-by: Brennan <brecon@microsoft.com>

Author: 3 people

aspnetcore/fundamentals/logging/index.md

@@ -12,7 +12,7 @@ uid: fundamentals/logging/index
 
 ::: moniker range=">= aspnetcore-3.0"
 
-By [Kirk Larkin](https://twitter.com/serpent5), [Rick Anderson](https://twitter.com/RickAndMSFT), [Tom Dykstra](https://github.com/tdykstra), and [Steve Smith](https://ardalis.com/)
+By [Kirk Larkin](https://twitter.com/serpent5), [Juergen Gutsch](https://github.com/JuergenGutsch) and [Rick Anderson](https://twitter.com/RickAndMSFT)
 
 .NET Core supports a logging API that works with a variety of built-in and third-party logging providers. This article shows how to use the logging API with built-in providers.
 
@@ -869,6 +869,68 @@ The following example shows how to register filter rules in code:
 * Log level `Information` and higher.
 * All categories starting with `"Microsoft"`.
 
+## Create a custom logger
+
+To add a custom logger, add an <xref:Microsoft.Extensions.Logging.ILoggerProvider> with <xref:Microsoft.Extensions.Logging.ILoggerFactory>:
+
+```csharp
+public void Configure(
+    IApplicationBuilder app,
+    IWebHostEnvironment env,
+    ILoggerFactory loggerFactory)
+{
+    loggerFactory.AddProvider(new CustomLoggerProvider(new CustomLoggerConfiguration()));
+```
+
+The `ILoggerProvider` creates one or more `ILogger` instances. The `ILogger` instances are used by the framework to log the information.
+
+### Sample custom logger configuration
+
+The sample:
+
+* Is designed to be a very basic sample that sets the color of the log console by event ID and log level. Loggers generally don't change by event ID and are not specific to log level.
+* Creates different colored console entries per log level and event ID using the following configuration type:
+
+[!code-csharp[](index/samples/3.x/CustomLogger/ColoredConsoleLogger/ColoredConsoleLoggerConfiguration.cs?name=snippet)]
+
+The preceding code sets the default level to `Warning` and the color to `Yellow`. If the `EventId` is set to 0, we will log all events.
+
+### Create the custom logger
+
+The `ILogger` implementation category name is typically the logging source. For example, the type where the logger is created:
+
+[!code-csharp[](index/samples/3.x/CustomLogger/ColoredConsoleLogger/ColoredConsoleLogger.cs?name=snippet)]
+
+The preceding code:
+
+* Creates a logger instance per category name.
+* Checks `logLevel == _config.LogLevel` in `IsEnabled`, so each `logLevel` has a unique logger. Generally, loggers should also be enabled for all higher log levels:
+
+```csharp
+public bool IsEnabled(LogLevel logLevel)
+{
+    return logLevel >= _config.LogLevel;
+}
+```
+
+### Create the custom LoggerProvider
+
+The `LoggerProvider` is the class that creates the logger instances. Maybe it is not needed to create a logger instance per category, but this makes sense for some Loggers, like NLog or log4net. Doing this you are also able to choose different logging output targets per category if needed:
+
+[!code-csharp[](index/samples/3.x/CustomLogger/ColoredConsoleLogger/ColoredConsoleLoggerProvider.cs?name=snippet)]
+
+In the preceding code, <xref:Microsoft.Build.Logging.LoggerDescription.CreateLogger*> creates a single instance of the `ColoredConsoleLogger` per category name and stores it in the [`ConcurrentDictionary<TKey,TValue>`](/dotnet/api/system.collections.concurrent.concurrentdictionary-2);
+
+### Usage and registration of the custom logger
+
+Register the logger in the `Startup.Configure`:
+
+[!code-csharp[](index/samples/3.x/CustomLogger/Startup.cs?name=snippet)]
+
+For the preceding code, provide at least one extension method for the `ILoggerFactory`:
+
+[!code-csharp[](index/samples/3.x/CustomLogger/ColoredConsoleLogger/ColoredConsoleLoggerExtensions.cs?name=snippet)]
+
 ## Additional resources
 
 * <xref:fundamentals/logging/loggermessage>

aspnetcore/fundamentals/logging/index/samples/3.x/CustomLogger/ColoredConsoleLogger/ColoredConsoleLogger.cs

@@ -0,0 +1,47 @@
+using System;
+using Microsoft.Extensions.Logging;
+
+namespace CustomLogger.ColoredConsoleLogger
+{
+    #region snippet
+    public class ColoredConsoleLogger : ILogger
+    {
+        private readonly string _name;
+        private readonly ColoredConsoleLoggerConfiguration _config;
+
+        public ColoredConsoleLogger(string name, ColoredConsoleLoggerConfiguration config)
+        {
+            _name = name;
+            _config = config;
+        }
+
+        public IDisposable BeginScope<TState>(TState state)
+        {
+            return null;
+        }
+
+        public bool IsEnabled(LogLevel logLevel)
+        {
+            return logLevel == _config.LogLevel;
+        }
+
+        public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, 
+                            Exception exception, Func<TState, Exception, string> formatter)
+        {
+            if (!IsEnabled(logLevel))
+            {
+                return;
+            }
+
+            if (_config.EventId == 0 || _config.EventId == eventId.Id)
+            {
+                var color = Console.ForegroundColor;
+                Console.ForegroundColor = _config.Color;
+                Console.WriteLine($"{logLevel} - {eventId.Id} " +
+                                  $"- {_name} - {formatter(state, exception)}");
+                Console.ForegroundColor = color;
+            }
+        }
+    }
+    #endregion
+}

aspnetcore/fundamentals/logging/index/samples/3.x/CustomLogger/ColoredConsoleLogger/ColoredConsoleLoggerConfiguration.cs

@@ -0,0 +1,14 @@
+using System;
+using Microsoft.Extensions.Logging;
+
+namespace CustomLogger.ColoredConsoleLogger
+{
+    #region snippet
+    public class ColoredConsoleLoggerConfiguration
+    {
+        public LogLevel LogLevel { get; set; } = LogLevel.Warning;
+        public int EventId { get; set; } = 0;
+        public ConsoleColor Color { get; set; } = ConsoleColor.Yellow;
+    }
+    #endregion
+}

aspnetcore/fundamentals/logging/index/samples/3.x/CustomLogger/ColoredConsoleLogger/ColoredConsoleLoggerExtensions.cs

@@ -0,0 +1,32 @@
+using System;
+using Microsoft.Extensions.Logging;
+
+namespace CustomLogger.ColoredConsoleLogger
+{
+    #region snippet
+    public static class ColoredConsoleLoggerExtensions
+    {
+        public static ILoggerFactory AddColoredConsoleLogger(
+                                          this ILoggerFactory loggerFactory, 
+                                          ColoredConsoleLoggerConfiguration config)
+        {
+            loggerFactory.AddProvider(new ColoredConsoleLoggerProvider(config));
+            return loggerFactory;
+        }
+        public static ILoggerFactory AddColoredConsoleLogger(
+                                          this ILoggerFactory loggerFactory)
+        {
+            var config = new ColoredConsoleLoggerConfiguration();
+            return loggerFactory.AddColoredConsoleLogger(config);
+        }
+        public static ILoggerFactory AddColoredConsoleLogger(
+                                        this ILoggerFactory loggerFactory, 
+                                        Action<ColoredConsoleLoggerConfiguration> configure)
+        {
+            var config = new ColoredConsoleLoggerConfiguration();
+            configure(config);
+            return loggerFactory.AddColoredConsoleLogger(config);
+        }
+    }
+    #endregion
+}

aspnetcore/fundamentals/logging/index/samples/3.x/CustomLogger/ColoredConsoleLogger/ColoredConsoleLoggerProvider.cs

@@ -0,0 +1,28 @@
+using System.Collections.Concurrent;
+using Microsoft.Extensions.Logging;
+
+namespace CustomLogger.ColoredConsoleLogger
+{
+    #region snippet
+    public class ColoredConsoleLoggerProvider : ILoggerProvider
+    {
+        private readonly ColoredConsoleLoggerConfiguration _config;
+        private readonly ConcurrentDictionary<string, ColoredConsoleLogger> _loggers = new ConcurrentDictionary<string, ColoredConsoleLogger>();
+
+        public ColoredConsoleLoggerProvider(ColoredConsoleLoggerConfiguration config)
+        {
+            _config = config;
+        }
+
+        public ILogger CreateLogger(string categoryName)
+        {
+            return _loggers.GetOrAdd(categoryName, name => new ColoredConsoleLogger(name, _config));
+        }
+
+        public void Dispose()
+        {
+            _loggers.Clear();
+        }
+    }
+    #endregion
+}

aspnetcore/fundamentals/logging/index/samples/3.x/CustomLogger/Controllers/HomeController.cs

@@ -0,0 +1,46 @@
+using System.Diagnostics;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Logging;
+using CustomLogger.Models;
+using Microsoft.Docs.Samples;
+
+namespace CustomLogger.Controllers
+{
+    public class HomeController : Controller
+    {
+        private readonly ILogger<HomeController> _logger;
+
+        public HomeController(ILogger<HomeController> logger)
+        {
+            _logger = logger;
+        }
+
+        public IActionResult Index()
+        {
+            var routeInfo = ControllerContext.ToCtxString();
+
+            _logger.LogInformation(routeInfo);
+            _logger.LogWarning(routeInfo + "Testing LogWarning" );
+            _logger.LogError("Not an error. Just to show the custom logger");
+
+            return View();
+        }
+
+        public IActionResult Privacy()
+        {
+            var routeInfo = ControllerContext.ToCtxString();
+
+            _logger.LogInformation(routeInfo);
+            _logger.LogWarning(routeInfo + "Testing LogWarning");
+            _logger.LogError("Not an error. Just to show the custom logger");
+
+            return View();
+        }
+
+        [ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
+        public IActionResult Error()
+        {
+            return View(new ErrorViewModel { RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier });
+        }
+    }
+}

aspnetcore/fundamentals/logging/index/samples/3.x/CustomLogger/CustomLogger.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>netcoreapp3.1</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Rick.Docs.Samples.RouteInfo" Version="1.0.0.4" />
+  </ItemGroup>
+
+</Project>

aspnetcore/fundamentals/logging/index/samples/3.x/CustomLogger/Models/ErrorViewModel.cs

@@ -0,0 +1,11 @@
+using System;
+
+namespace CustomLogger.Models
+{
+    public class ErrorViewModel
+    {
+        public string RequestId { get; set; }
+
+        public bool ShowRequestId => !string.IsNullOrEmpty(RequestId);
+    }
+}

aspnetcore/fundamentals/logging/index/samples/3.x/CustomLogger/Program.cs

@@ -0,0 +1,26 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+
+namespace CustomLogger
+{
+    public class Program
+    {
+        public static void Main(string[] args)
+        {
+            CreateHostBuilder(args).Build().Run();
+        }
+
+        public static IHostBuilder CreateHostBuilder(string[] args) =>
+            Host.CreateDefaultBuilder(args)
+                .ConfigureWebHostDefaults(webBuilder =>
+                {
+                    webBuilder.UseStartup<Startup>();
+                });
+    }
+}

aspnetcore/fundamentals/logging/index/samples/3.x/CustomLogger/Startup.cs

@@ -0,0 +1,80 @@
+using System;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using CustomLogger.ColoredConsoleLogger;
+
+namespace CustomLogger
+{
+    public class Startup
+    {
+        public Startup(IConfiguration configuration)
+        {
+            Configuration = configuration;
+        }
+
+        public IConfiguration Configuration { get; }
+
+        public void ConfigureServices(IServiceCollection services)
+        {
+            services.AddControllersWithViews();
+        }
+
+        #region snippet
+        public void Configure(IApplicationBuilder app, IWebHostEnvironment env, 
+                              ILoggerFactory loggerFactory)
+        {
+            // Default registration.
+            loggerFactory.AddProvider(new ColoredConsoleLoggerProvider(
+                                      new ColoredConsoleLoggerConfiguration
+            {
+                LogLevel = LogLevel.Error,
+                Color = ConsoleColor.Red
+            }));
+
+            // Custom registration with default values.
+            loggerFactory.AddColoredConsoleLogger();
+
+            // Custom registration with a new configuration instance.
+            loggerFactory.AddColoredConsoleLogger(new ColoredConsoleLoggerConfiguration
+            {
+                LogLevel = LogLevel.Debug,
+                Color = ConsoleColor.Gray
+            });
+
+            // Custom registration with a configuration object.
+            loggerFactory.AddColoredConsoleLogger(c =>
+            {
+                c.LogLevel = LogLevel.Information;
+                c.Color = ConsoleColor.Blue;
+            });
+
+            if (env.IsDevelopment())
+            {
+                app.UseDeveloperExceptionPage();
+            }
+            else
+            {
+                app.UseExceptionHandler("/Home/Error");
+                app.UseHsts();
+            }
+            app.UseHttpsRedirection();
+            app.UseStaticFiles();
+
+            app.UseRouting();
+
+            app.UseAuthorization();
+
+            app.UseEndpoints(endpoints =>
+            {
+                endpoints.MapControllerRoute(
+                    name: "default",
+                    pattern: "{controller=Home}/{action=Index}/{id?}");
+            });
+        }
+        #endregion
+    }
+}