.NET 라이브러리 작성자를 위한 옵션 패턴 지침

아티클
06/23/2023

종속성 주입의 도움으로 서비스 및 해당 구성을 등록하면 ‘옵션 패턴’을 사용할 수 있습니다. 옵션 패턴을 사용하면 라이브러리(및 서비스)의 소비자가 옵션 인터페이스 인스턴스를 요구할 수 있습니다. 여기서 TOptions는 옵션 클래스입니다. 강력한 형식의 개체를 통해 구성 옵션을 사용하면 일관된 값 표현을 보장하고, 데이터 주석으로 유효성을 검사할 수 있으며, 문자열 값을 수동으로 구문 분석해야 하는 부담이 없어집니다. 라이브러리의 소비자가 사용할 수 있는 구성 공급자가 많이 있습니다. 이러한 공급자를 통해 소비자는 여러 방법으로 라이브러리를 구성할 수 있습니다.

이 문서에서는 .NET 라이브러리 작성자가 라이브러리의 소비자에게 옵션 패턴을 올바르게 노출하는 방법에 대한 일반적인 지침을 알아봅니다. 여러 방법으로 동일한 목적을 달성할 수 있으며 몇 가지 고려할 사항이 있습니다.

명명 규칙

규칙에 따라 서비스 등록을 담당하는 확장 메서드는 이름이 Add{Service}로 지정됩니다. 여기서 {Service}는 의미 있고 설명이 포함된 이름입니다. Add{Service} 확장 메서드는 ASP.NET Core와 .NET 모두에서 일반적입니다.

✔️ 서비스를 다른 제품과 명확하게 구분하는 이름을 고려하세요.

❌ 공식 Microsoft 패키지의 .NET 에코시스템에 이미 포함된 이름은 사용하지 마세요.

✔️ 확장 메서드를 노출하는 정적 클래스의 이름을 {Type}Extensions로 지정하는 것이 좋습니다. 여기서 {Type}는 확장하는 형식입니다.

네임스페이스 지침

Microsoft 패키지는 Microsoft.Extensions.DependencyInjection 네임스페이스를 활용하여 다양한 서비스 제품의 등록을 통합합니다.

✔️ 패키지 제품을 명확하게 식별하는 네임스페이스를 고려하세요.

❌ 비공식 Microsoft 패키지에 Microsoft.Extensions.DependencyInjection 네임스페이스를 사용하지 마세요.

매개 변수가 없음

서비스를 최소한의 구성으로 또는 명시적 구성 없이 사용할 수 있는 경우에는 매개 변수가 없는 확장 메서드를 사용하는 것이 좋습니다.

using Microsoft.Extensions.DependencyInjection;

namespace ExampleLibrary.Extensions.DependencyInjection;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddMyLibraryService(
        this IServiceCollection services)
    {
        services.AddOptions<LibraryOptions>()
            .Configure(options =>
            {
                // Specify default option values
            });

        // Register lib services here...
        // services.AddScoped<ILibraryService, DefaultLibraryService>();

        return services;
    }
}

위의 코드에서 AddMyLibraryService는

IServiceCollection의 인스턴스를 확장합니다.
LibraryOptions의 형식 매개 변수를 사용하여 OptionsServiceCollectionExtensions.AddOptions<TOptions>(IServiceCollection)를 호출합니다.
기본 옵션 값을 지정하는 Configure에 대한 호출을 연결합니다.

`IConfiguration` 매개 변수

소비자에게 많은 옵션을 노출하는 라이브러리를 작성하는 경우 IConfiguration 매개 변수 확장 메서드를 요구하는 것이 좋습니다. 필요한 IConfiguration 인스턴스는 IConfiguration.GetSection 함수를 사용하여 구성의 명명된 섹션으로 범위가 지정되어야 합니다.

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace ExampleLibrary.Extensions.DependencyInjection;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddMyLibraryService(
      this IServiceCollection services,
      IConfiguration namedConfigurationSection)
    {
        // Default library options are overridden
        // by bound configuration values.
        services.Configure<LibraryOptions>(namedConfigurationSection);

        // Register lib services here...
        // services.AddScoped<ILibraryService, DefaultLibraryService>();

        return services;
    }
}

팁

Configure<TOptions>(IServiceCollection, IConfiguration) 메서드는 Microsoft.Extensions.Options.ConfigurationExtensions NuGet 패키지의 일부입니다.

위의 코드에서 AddMyLibraryService는

IServiceCollection의 인스턴스를 확장합니다.
IConfiguration 매개 변수 namedConfigurationSection을 정의합니다.
구성할 LibraryOptions 제네릭 형식 매개 변수와 namedConfigurationSection 인스턴스를 전달하는 Configure<TOptions>(IServiceCollection, IConfiguration)를 호출합니다.

이 패턴의 소비자는 명명된 섹션의 범위가 지정된 IConfiguration 인스턴스를 제공합니다.

using ExampleLibrary.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddMyLibraryService(
    builder.Configuration.GetSection("LibraryOptions"));

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

.AddMyLibraryService 호출은 IServiceCollection 형식에서 이루어집니다.

기본값 지정은 라이브러리 작성자가 해야 합니다.

참고 항목

구성을 옵션 인스턴스에 바인딩할 수 있습니다. 그러나 이름 충돌 때문에 오류가 발생할 위험이 있습니다. 또한 이렇게 수동으로 바인딩하는 경우 옵션 패턴 소비를 한 번만 읽기로 제한합니다. 이러한 소비자는 IOptionsMonitor 인터페이스를 사용할 수 없기 때문에 설정 변경 사항이 다시 바인딩되지 않습니다.

services.AddOptions<LibraryOptions>()
    .Configure<IConfiguration>(
        (options, configuration) =>
            configuration.GetSection("LibraryOptions").Bind(options));

대신 BindConfiguration 확장 메서드를 사용해야 합니다. 이 확장 메서드는 구성을 옵션 인스턴스에 바인딩하고 구성 섹션에 대한 변경 토큰 원본도 등록합니다. 이를 통해 소비자는 IOptionsMonitor 인터페이스를 사용할 수 있습니다.

구성 섹션 경로 매개 변수

라이브러리의 소비자는 기본 TOptions 형식을 바인딩하는 구성 섹션 경로를 지정할 수 있습니다. 이 시나리오에서는 확장 메서드에서 string 매개 변수를 정의합니다.

using Microsoft.Extensions.DependencyInjection;

namespace ExampleLibrary.Extensions.DependencyInjection;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddMyLibraryService(
      this IServiceCollection services,
      string configSectionPath)
    {
        services.AddOptions<SupportOptions>()
            .BindConfiguration(configSectionPath)
            .ValidateDataAnnotations()
            .ValidateOnStart();

        // Register lib services here...
        // services.AddScoped<ILibraryService, DefaultLibraryService>();

        return services;
    }
}

위의 코드에서 AddMyLibraryService는

IServiceCollection의 인스턴스를 확장합니다.
string 매개 변수 configSectionPath를 정의합니다.
호출:
- SupportOptions의 제네릭 형식 매개 변수를 사용하여 AddOptions
- 지정된 configSectionPath 매개 변수를 사용하여 BindConfiguration
- 데이터 주석 유효성 검사를 사용하도록 설정하기 위해 ValidateDataAnnotations
- 런타임이 아닌 시작 시 유효성 검사를 적용하기 위해 ValidateOnStart

다음 예제에서는 Microsoft.Extensions.Options.DataAnnotations NuGet 패키지를 사용하여 데이터 주석 유효성 검사를 사용하도록 설정합니다. SupportOptions 클래스는 다음과 같이 정의됩니다.

using System.ComponentModel.DataAnnotations;

public sealed class SupportOptions
{
    [Url]
    public string? Url { get; set; }

    [Required, EmailAddress]
    public required string Email { get; set; }

    [Required, DataType(DataType.PhoneNumber)]
    public required string PhoneNumber { get; set; }
}

다음 JSON appsettings.json 파일이 사용된다고 상상해 보세요.

{
    "Support": {
        "Url": "https://support.example.com",
        "Email": "help@support.example.com",
        "PhoneNumber": "+1(888)-SUPPORT"
    }
}

`Action<TOptions>` 매개 변수

라이브러리 소비자가 옵션 클래스의 인스턴스를 생성하는 람다 식을 제공하는 데 관심이 있을 수 있습니다. 이 시나리오에서는 확장 메서드에서 Action<LibraryOptions> 매개 변수를 정의합니다.

using Microsoft.Extensions.DependencyInjection;

namespace ExampleLibrary.Extensions.DependencyInjection;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddMyLibraryService(
        this IServiceCollection services,
        Action<LibraryOptions> configureOptions)
    {
        services.Configure(configureOptions);

        // Register lib services here...
        // services.AddScoped<ILibraryService, DefaultLibraryService>();

        return services;
    }
}

위의 코드에서 AddMyLibraryService는

IServiceCollection의 인스턴스를 확장합니다.
Action<T> 매개 변수 configureOptions를 정의합니다. 여기서 T는 LibraryOptions입니다.
configureOptions 작업이 지정되면 Configure를 호출합니다.

이 패턴의 소비자는 람다 식(또는 Action<LibraryOptions> 매개 변수를 충족하는 대리자)을 제공합니다.

using ExampleLibrary.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddMyLibraryService(options =>
{
    // User defined option values
    // options.SomePropertyValue = ...
});
                                                                        
using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

옵션 인스턴스 매개 변수

라이브러리 소비자가 인라인 옵션 인스턴스를 제공하는 것을 선호할 수 있습니다. 이 시나리오에서는 옵션 개체 LibraryOptions의 인스턴스를 사용하는 확장 메서드를 노출합니다.

using Microsoft.Extensions.DependencyInjection;

namespace ExampleLibrary.Extensions.DependencyInjection;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddMyLibraryService(
      this IServiceCollection services,
      LibraryOptions userOptions)
    {
        services.AddOptions<LibraryOptions>()
            .Configure(options =>
            {
                // Overwrite default option values
                // with the user provided options.
                // options.SomeValue = userOptions.SomeValue;
            });

        // Register lib services here...
        // services.AddScoped<ILibraryService, DefaultLibraryService>();

        return services;
    }
}

위의 코드에서 AddMyLibraryService는

IServiceCollection의 인스턴스를 확장합니다.
LibraryOptions의 형식 매개 변수를 사용하여 OptionsServiceCollectionExtensions.AddOptions<TOptions>(IServiceCollection)를 호출합니다.
지정된 userOptions 인스턴스에서 재정의할 수 있는 기본 옵션 값을 지정하는 Configure에 대한 호출을 연결합니다.

이 패턴의 소비자는 LibraryOptions 클래스의 인스턴스를 제공하여 원하는 속성 값을 인라인으로 정의합니다.

using ExampleLibrary.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddMyLibraryService(new LibraryOptions
{
    // Specify option values
    // SomePropertyValue = ...
});

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

구성 후

모든 구성 옵션 값을 바인딩하거나 지정한 후에는 사후 구성 기능을 사용할 수 있습니다. 앞서 설명한 것과 동일한 Action<TOptions> 매개 변수를 노출하여 PostConfigure를 호출하도록 선택할 수 있습니다. 사후 구성은 모든 .Configure 호출 후에 실행됩니다. PostConfigure를 사용하는 것을 고려하려는 몇 가지 이유가 있습니다.

실행 순서: .Configure 호출에 설정된 구성 값을 재정의할 수 있습니다.
유효성 검사: 다른 모든 구성이 적용된 후 기본값이 설정되었는지 확인할 수 있습니다.

using Microsoft.Extensions.DependencyInjection;

namespace ExampleLibrary.Extensions.DependencyInjection;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddMyLibraryService(
      this IServiceCollection services,
      Action<LibraryOptions> configureOptions)
    {
        services.PostConfigure(configureOptions);

        // Register lib services here...
        // services.AddScoped<ILibraryService, DefaultLibraryService>();

        return services;
    }
}

위의 코드에서 AddMyLibraryService는

IServiceCollection의 인스턴스를 확장합니다.
Action<T> 매개 변수 configureOptions를 정의합니다. 여기서 T는 LibraryOptions입니다.
configureOptions 작업이 지정되면 PostConfigure를 호출합니다.

이 패턴의 소비자는 사후 구성을 사용하지 않는 시나리오의 Action<TOptions> 매개 변수와 마찬가지로 람다 식(또는 Action<LibraryOptions> 매개 변수를 충족하는 대리자)을 제공합니다.

using ExampleLibrary.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Services.AddMyLibraryService(options =>
{
    // Specify option values
    // options.SomePropertyValue = ...
});

using IHost host = builder.Build();

// Application code should start here.

await host.RunAsync();

다음을 통해 공유

.NET 라이브러리 작성자를 위한 옵션 패턴 지침

명명 규칙

네임스페이스 지침

매개 변수가 없음

`IConfiguration` 매개 변수

구성 섹션 경로 매개 변수

`Action<TOptions>` 매개 변수

옵션 인스턴스 매개 변수

구성 후

참고 항목

추가 리소스

다음을 통해 공유

.NET 라이브러리 작성자를 위한 옵션 패턴 지침

명명 규칙

네임스페이스 지침

매개 변수가 없음

IConfiguration 매개 변수

구성 섹션 경로 매개 변수

Action<TOptions> 매개 변수

옵션 인스턴스 매개 변수

구성 후

참고 항목

추가 리소스

`IConfiguration` 매개 변수

`Action<TOptions>` 매개 변수