HttpClientBuilderExtensions.Logging.cs

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System;
using Microsoft.Extensions.Http;
using Microsoft.Extensions.Http.Logging;

namespace Microsoft.Extensions.DependencyInjection
{
    public static partial class HttpClientBuilderExtensions
    {
        /// <summary>
        /// Adds a delegate that will be used to create an additional logger for a named <see cref="System.Net.Http.HttpClient"/>. The custom logger would be invoked
        /// from a dedicated logging DelegatingHandler on every request of the corresponding named <see cref="System.Net.Http.HttpClient"/>.
        /// </summary>
        /// <param name="builder">The <see cref="IHttpClientBuilder"/>.</param>
        /// <param name="httpClientLoggerFactory">A delegate that is used to create a custom logger. The logger should implement
        /// <see cref="IHttpClientLogger"/> or <see cref="IHttpClientAsyncLogger"/>.</param>
        /// <param name="wrapHandlersPipeline">Whether the logging handler with the custom logger would be added to the top
        /// or to the bottom of the additional handlers chains.</param>
        /// <returns>An <see cref="IHttpClientBuilder"/> that can be used to configure the client.</returns>
        /// <remarks>
        /// <para>
        /// If the <see paramref="wrapHandlersPipeline"/> is `true`, <see cref="IHttpClientLogger.LogRequestStart"/> and
        /// <see cref="IHttpClientAsyncLogger.LogRequestStartAsync"/> would be executed before all
        /// other additional handlers in the chain. <see cref="IHttpClientLogger.LogRequestStop"/> and
        /// <see cref="IHttpClientAsyncLogger.LogRequestStopAsync"/> would be executed after all
        /// other additional handlers, essentially wrapping the whole pipeline.
        /// </para>
        /// <para>
        /// If the <see paramref="wrapHandlersPipeline"/> is `false`, <see cref="IHttpClientLogger.LogRequestStart"/> and
        /// <see cref="IHttpClientAsyncLogger.LogRequestStartAsync"/> would be executed after all
        /// other additional handlers in the chain, right before the primary handler. <see cref="IHttpClientLogger.LogRequestStop"/> and
        /// <see cref="IHttpClientAsyncLogger.LogRequestStopAsync"/> would be executed before all
        /// other additional handlers, right after the primary handler.
        /// </para>
        /// <para>
        /// The <see cref="IServiceProvider"/> argument provided to <paramref name="httpClientLoggerFactory"/> will be
        /// a reference to a scoped service provider that shares the lifetime of the handler chain being constructed.
        /// </para>
        /// <para>
        /// If <see cref="AddLogger"/> is called multiple times, multiple loggers would be added. If <see cref="RemoveAllLoggers"/> was
        /// not called before calling <see cref="AddLogger"/>, then new logger would be added in addition to the default ones.
        /// </para>
        /// </remarks>
        public static IHttpClientBuilder AddLogger(this IHttpClientBuilder builder, Func<IServiceProvider, IHttpClientLogger> httpClientLoggerFactory, bool wrapHandlersPipeline = false)
        {
            ThrowHelper.ThrowIfNull(builder);
            ThrowHelper.ThrowIfNull(httpClientLoggerFactory);

            builder.Services.Configure<HttpClientFactoryOptions>(builder.Name, options =>
            {
                options.LoggingBuilderActions.Add(b =>
                {
                    IHttpClientLogger httpClientLogger = httpClientLoggerFactory(b.Services);
                    HttpClientLoggerHandler handler = new HttpClientLoggerHandler(httpClientLogger);

                    if (wrapHandlersPipeline)
                    {
                        b.AdditionalHandlers.Insert(0, handler);
                    }
                    else
                    {
                        b.AdditionalHandlers.Add(handler);
                    }
                });
            });

            return builder;
        }

        /// <summary>
        /// Adds a delegate that will be used to create an additional logger for a named <see cref="System.Net.Http.HttpClient"/>. The custom logger would be invoked
        /// from a dedicated logging DelegatingHandler on every request of the corresponding named <see cref="System.Net.Http.HttpClient"/>.
        /// </summary>
        /// <param name="builder">The <see cref="IHttpClientBuilder"/>.</param>
        /// <param name="wrapHandlersPipeline">Whether the logging handler with the custom logger would be added to the top
        /// or to the bottom of the additional handlers chains.</param>
        /// <returns>An <see cref="IHttpClientBuilder"/> that can be used to configure the client.</returns>
        /// <typeparam name="TLogger">
        /// The service type of the custom logger as it was registered in DI. The logger should implement <see cref="IHttpClientLogger"/>
        /// or <see cref="IHttpClientAsyncLogger"/>.
        /// </typeparam>
        /// <remarks>
        /// <para>
        /// If the <see paramref="wrapHandlersPipeline"/> is `true`, <see cref="IHttpClientLogger.LogRequestStart"/> and
        /// <see cref="IHttpClientAsyncLogger.LogRequestStartAsync"/> would be executed before all
        /// other additional handlers in the chain. <see cref="IHttpClientLogger.LogRequestStop"/> and
        /// <see cref="IHttpClientAsyncLogger.LogRequestStopAsync"/> would be executed after all
        /// other additional handlers, essentially wrapping the whole pipeline.
        /// </para>
        /// <para>
        /// If the <see paramref="wrapHandlersPipeline"/> is `false`, <see cref="IHttpClientLogger.LogRequestStart"/> and
        /// <see cref="IHttpClientAsyncLogger.LogRequestStartAsync"/> would be executed after all
        /// other additional handlers in the chain, right before the primary handler. <see cref="IHttpClientLogger.LogRequestStop"/> and
        /// <see cref="IHttpClientAsyncLogger.LogRequestStopAsync"/> would be executed before all
        /// other additional handlers, right after the primary handler.
        /// </para>
        /// <para>
        /// The <typeparamref name="TLogger"/> will be resolved from a scoped service provider that shares
        /// the lifetime of the handler chain being constructed.
        /// </para>
        /// <para>
        /// If <see cref="AddLogger{TLogger}"/> is called multiple times, multiple loggers would be added. If <see cref="RemoveAllLoggers"/> was
        /// not called before calling <see cref="AddLogger{TLogger}"/>, then new logger would be added in addition to the default ones.
        /// </para>
        /// </remarks>
        public static IHttpClientBuilder AddLogger<TLogger>(this IHttpClientBuilder builder, bool wrapHandlersPipeline = false)
            where TLogger : IHttpClientLogger
        {
            ThrowHelper.ThrowIfNull(builder);

            return AddLogger(builder, services => services.GetRequiredService<TLogger>(), wrapHandlersPipeline);
        }

        /// <summary>
        /// Removes all previously added loggers for a named <see cref="System.Net.Http.HttpClient"/>, including default ones.
        /// </summary>
        /// <param name="builder">The <see cref="IHttpClientBuilder"/>.</param>
        /// <returns>An <see cref="IHttpClientBuilder"/> that can be used to configure the client.</returns>
        public static IHttpClientBuilder RemoveAllLoggers(this IHttpClientBuilder builder)
        {
            ThrowHelper.ThrowIfNull(builder);

            builder.Services.Configure<HttpClientFactoryOptions>(builder.Name, options =>
            {
                options.LoggingBuilderActions.Clear();
                options.SuppressDefaultLogging = true;
            });

            return builder;
        }

        /// <summary>
        /// Adds back the default logging for a named <see cref="System.Net.Http.HttpClient"/>, if it was removed previously by calling <see cref="RemoveAllLoggers"/>.
        /// </summary>
        /// <param name="builder">The <see cref="IHttpClientBuilder"/>.</param>
        /// <returns>An <see cref="IHttpClientBuilder"/> that can be used to configure the client.</returns>
        public static IHttpClientBuilder AddDefaultLogger(this IHttpClientBuilder builder)
        {
            ThrowHelper.ThrowIfNull(builder);

            builder.Services.Configure<HttpClientFactoryOptions>(builder.Name, options => options.SuppressDefaultLogging = false);
            return builder;
        }
    }
}