ASP.NET Core의 .NET 일반 호스트

ASP.NET Core 템플릿은 .NET Core 일반 호스트(HostBuilder)를 만듭니다.

이 항목에서는 ASP.NET Core에서 .NET 일반 호스트를 사용하는 방법에 관한 정보를 제공합니다. 콘솔 앱에서 .NET 일반 호스트를 사용하는 방법에 관한 자세한 내용은 .NET 일반 호스트를 참조하세요.

호스트 정의

호스트 는 다음과 같이 앱의 리소스를 캡슐화하는 개체입니다.

  • DI(종속성 주입)
  • 로깅
  • Configuration
  • IHostedService 구현

호스트가 시작될 때 서비스 컨테이너의 호스티드 서비스 컬렉션에 등록된 IHostedService의 각 구현에서 IHostedService.StartAsync을 호출합니다. 웹앱에서 IHostedService 구현 중 하나는 HTTP 서버 구현을 시작하는 웹 서비스입니다.

하나의 개체에 앱의 모든 상호 종속적 리소스를 포함하는 주요 원인은 수명 관리 즉, 앱 시작 및 종료에 대한 제어 때문입니다.

호스트 설정

호스트는 일반적으로 Program 클래스의 코드로 구성, 빌드 및 실행됩니다. Main 메서드는 다음 작업을 수행합니다.

  • CreateHostBuilder 메서드를 호출하여 작성기 개체를 만들고 구성합니다.
  • 작성기 개체에서 BuildRun 메서드를 호출합니다.

ASP.NET Core 웹 템플릿은 다음과 같은 코드를 생성하여 호스트를 만듭니다.

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>();
            });
}

다음 코드는 DI 컨테이너에 IHostedService 구현이 추가된 비 HTTP 워크로드를 만듭니다.

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

HTTP 워크로드의 경우 Main 메서드는 동일하지만 CreateHostBuilderConfigureWebHostDefaults를 호출합니다.

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

앱에서 Entity Framework Core를 사용하는 경우 CreateHostBuilder 메서드의 이름이나 서명을 변경하지 마세요. Entity Framework Core 도구는 앱을 실행하지 않고 호스트를 구성하는 CreateHostBuilder 메서드를 찾으려고 합니다. 자세한 내용은 디자인 타임 DbContext 만들기를 참조하세요.

기본 작성기 설정

CreateDefaultBuilder 메서드는 다음 작업을 수행합니다.

  • 콘텐츠 루트GetCurrentDirectory에서 반환된 경로로 설정합니다.
  • 다음에서 호스트 구성을 로드합니다.
    • 접두사가 DOTNET_인 환경 변수.
    • 명령줄 인수.
  • 다음에서 앱 구성을 로드합니다.
    • appsettings.json.
    • appsettings.{Environment}.json.
    • 사용자 비밀 - 앱이 Development 환경에서 실행되는 경우.
    • 환경 변수.
    • 명령줄 인수.
  • 다음 로깅 공급자를 추가합니다.
    • Console
    • Debug
    • EventSource
    • EventLog(Windows에서 실행 중인 경우에만)
  • 환경이 개발 중일 때 범위 유효성 검사종속성 유효성 검사를 사용하도록 설정합니다.

ConfigureWebHostDefaults 메서드는 다음 작업을 수행합니다.

이 문서 뒷부분의 모든 앱 유형에 대한 설정웹앱 설정 섹션에서는 기본 작성기 설정을 재정의하는 방법을 보여줍니다.

프레임워크에서 제공하는 서비스

다음 서비스가 자동으로 등록됩니다.

프레임워크에서 제공하는 서비스에 대한 자세한 내용은 ASP.NET Core에서 종속성 주입를 참조하세요.

IHostApplicationLifetime

IHostApplicationLifetime(이전의 IApplicationLifetime) 서비스를 모든 클래스에 삽입하여 사후 시작 및 정상 종료 작업을 처리합니다. 인터페이스의 세 가지 속성은 앱 시작 및 앱 중지 이벤트 처리기 메서드를 등록하는 데 사용되는 취소 토큰입니다. 인터페이스에는 StopApplication 메서드도 포함됩니다.

다음 예제는 IHostApplicationLifetime 이벤트를 등록하는 IHostedService 구현입니다.

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IHostApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IHostApplicationLifetime appLifetime)
    {
        _logger = logger;
        _appLifetime = appLifetime;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _appLifetime.ApplicationStarted.Register(OnStarted);
        _appLifetime.ApplicationStopping.Register(OnStopping);
        _appLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    private void OnStarted()
    {
        _logger.LogInformation("OnStarted has been called.");

        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        _logger.LogInformation("OnStopping has been called.");

        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        _logger.LogInformation("OnStopped has been called.");

        // Perform post-stopped activities here
    }
}

IHostLifetime

IHostLifetime 구현은 호스트가 시작될 때와 중지될 때를 제어합니다. 등록된 마지막 구현이 사용됩니다.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime은 기본 IHostLifetime 구현입니다. ConsoleLifetime:

IHostEnvironment

IHostEnvironment 서비스를 클래스에 삽입하여 다음 설정에 대한 정보를 가져옵니다.

웹앱은 IHostEnvironment를 상속하고 WebRootPath를 추가하는 IWebHostEnvironment 인터페이스를 구현합니다.

호스트 구성

호스트 구성은 IHostEnvironment 구현의 속성에 사용됩니다.

호스트 구성은 ConfigureAppConfiguration 내부에 HostBuilderContext.Configuration에서 사용할 수 있습니다. ConfigureAppConfiguration 다음에 HostBuilderContext.Configuration이 앱 구성으로 대체됩니다.

호스트 구성을 추가하려면 IHostBuilder에서 ConfigureHostConfiguration을 호출합니다. ConfigureHostConfiguration 항목은 부가적 결과와 함께 여러 번 호출할 수 있습니다. 호스트는 지정된 키에 마지막으로 값을 설정하는 옵션을 사용합니다.

접두사 DOTNET_ 및 명령줄 인수가 있는 환경 변수 공급자는 CreateDefaultBuilder에 포함되어 있습니다. 웹앱의 경우 접두사 ASPNETCORE_가 있는 환경 변수 공급자가 추가됩니다. 접두사는 환경 변수를 읽을 때 제거됩니다. 예를 들어 ASPNETCORE_ENVIRONMENT의 환경 변수 값이 environment 키에 대한 호스트 구성 값이 됩니다.

다음 예제에서는 호스트 구성을 만듭니다.

// using Microsoft.Extensions.Configuration;

Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(configHost =>
    {
        configHost.SetBasePath(Directory.GetCurrentDirectory());
        configHost.AddJsonFile("hostsettings.json", optional: true);
        configHost.AddEnvironmentVariables(prefix: "PREFIX_");
        configHost.AddCommandLine(args);
    });

앱 구성

앱 구성은 IHostBuilder에서 ConfigureAppConfiguration을 호출하여 생성됩니다. ConfigureAppConfiguration 항목은 부가적 결과와 함께 여러 번 호출할 수 있습니다. 앱은 지정된 키에 마지막으로 값을 설정하는 옵션을 사용합니다.

ConfigureAppConfiguration에 의해 생성된 구성은 다음 작업을 위해 HostBuilderContext.Configuration에서 사용 가능하거나 DI의 서비스로 사용할 수 있습니다. 호스트 구성도 앱 구성에 추가됩니다.

자세한 내용은 ASP.NET Core의 구성을 참조하세요.

모든 앱 유형에 대한 설정

이 섹션에는 HTTP 및 비 HTTP 워크로드 모두에 적용되는 호스트 설정이 나열되어 있습니다. 기본적으로 이러한 설정을 구성하는 데 사용되는 환경 변수에는 DOTNET_ 또는 ASPNETCORE_ 접두사가 있을 수 있습니다. 자세한 내용은 기본 작성기 설정 섹션을 참조하세요.

ApplicationName

호스트를 생성하는 동안 호스트 구성에서 IHostEnvironment.ApplicationName 속성을 설정합니다.

: applicationName
형식: string
기본값: 앱의 진입점을 포함하는 어셈블리의 이름입니다.
환경 변수: <PREFIX_>APPLICATIONNAME

이 값을 설정하려면 환경 변수를 사용합니다.

ContentRoot

IHostEnvironment.ContentRootPath 속성은 콘텐츠 파일 검색을 시작하는 위치를 결정합니다. 경로가 존재하지 않는 경우 호스트가 시작되지 않습니다.

: contentRoot
형식: string
기본값: 앱 어셈블리가 있는 폴더입니다.
환경 변수: <PREFIX_>CONTENTROOT

이 값을 설정하려면 환경 변수를 사용하거나 IHostBuilder에서 UseContentRoot를 호출합니다.

Host.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\content-root")
    //...

자세한 내용은 다음을 참조하세요.

EnvironmentName

IHostEnvironment.EnvironmentName 속성을 임의의 값으로 설정할 수 있습니다. 프레임워크에서 정의된 값은 Development, StagingProduction을 포함합니다. 값은 대/소문자를 구분하지 않습니다.

: environment
형식: string
기본: Production
환경 변수: <PREFIX_>ENVIRONMENT

이 값을 설정하려면 환경 변수를 사용하거나 IHostBuilder에서 UseEnvironment를 호출합니다.

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    //...

ShutdownTimeout

HostOptions.ShutdownTimeoutStopAsync에 대한 시간 제한을 설정합니다. 기본값은 5초입니다. 시간 제한 기간 동안 호스트는 다음을 수행합니다.

모든 호스팅된 서비스가 중지하기 전에 시간 제한 기간이 만료되면 앱이 종료될 때 모든 활성화된 나머지 서비스가 중지됩니다. 처리를 완료하지 않은 경우에도 서비스가 중지됩니다. 서비스를 중지하는 데 시간이 더 필요한 경우 시간 제한을 늘립니다.

: shutdownTimeoutSeconds
형식: int
기본값: 5초
환경 변수: <PREFIX_>SHUTDOWNTIMEOUTSECONDS

이 값을 설정하려면 환경 변수를 사용하거나 HostOptions를 구성합니다. 다음 예제에서는 시간 제한을 20초로 설정합니다.

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    });

변경 시 앱 구성 다시 로드 사용 안 함

기본적으로 파일이 변경되면 appsettings.jsonappsettings.{Environment}.json 이 다시 로드됩니다. ASP.NET Core 5.0 이상에서 해당 다시 로드 동작을 사용하지 않도록 설정하려면 hostBuilder:reloadConfigOnChange 키를 false로 설정합니다.

: hostBuilder:reloadConfigOnChange
형식: bool(true 또는 1)
기본: true
명령줄 인수: hostBuilder:reloadConfigOnChange
환경 변수: <PREFIX_>hostBuilder:reloadConfigOnChange

경고

콜론(:) 구분 기호는 모든 플랫폼의 환경 변수 계층적 키에서 작동하지 않습니다. 자세한 내용은 환경 변수를 참조하세요.

웹앱 설정

일부 호스트 설정은 HTTP 워크로드에만 적용됩니다. 기본적으로 이러한 설정을 구성하는 데 사용되는 환경 변수에는 DOTNET_ 또는 ASPNETCORE_ 접두사가 있을 수 있습니다.

이러한 설정에 대해 IWebHostBuilder의 확장 메서드를 사용할 수 있습니다. 확장 메서드를 호출하는 방법을 보여주는 코드 샘플은 다음 예제와 같이 webBuilderIWebHostBuilder의 인스턴스라고 가정합니다.

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

CaptureStartupErrors

false인 경우 시작 시 오류가 발생하면 호스트가 종료됩니다. true이면 호스트가 시작 시 예외를 캡처하고 서버 시작을 시도합니다.

: captureStartupErrors
형식: bool(true 또는 1)
기본값: 기본값이 true인 IIS 뒤에 있는 Kestrel으로 앱이 실행하지 않는 한 기본값은 false로 지정됩니다.
환경 변수: <PREFIX_>CAPTURESTARTUPERRORS

이 값을 설정하려면 구성을 사용하거나 CaptureStartupErrors를 호출합니다.

webBuilder.CaptureStartupErrors(true);

DetailedErrors

활성화하거나 환경이 Development인 경우 앱은 자세한 오류를 캡처합니다.

: detailedErrors
형식: bool(true 또는 1)
기본: false
환경 변수: <PREFIX_>_DETAILEDERRORS

이 값을 설정하려면 구성을 사용하거나 UseSetting을 호출합니다.

webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");

HostingStartupAssemblies

시작 시 로드할 호스팅 시작 어셈블리의 세미콜론으로 구분된 문자열입니다. 구성 값의 기본값이 빈 문자열이지만, 호스팅 시작 어셈블리는 항상 앱의 어셈블리를 포함합니다. 호스팅 시작 어셈블리가 제공되는 경우, 시작 시 앱이 일반적인 서비스를 빌드할 때 로드를 위해 앱의 어셈블리에 추가됩니다.

: hostingStartupAssemblies
형식: string
기본값: 빈 문자열
환경 변수: <PREFIX_>_HOSTINGSTARTUPASSEMBLIES

이 값을 설정하려면 구성을 사용하거나 UseSetting을 호출합니다.

webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

HostingStartupExcludeAssemblies

시작 시 제외할 호스팅 시작 어셈블리의 세미콜론으로 구분된 문자열입니다.

: hostingStartupExcludeAssemblies
형식: string
기본값: 빈 문자열
환경 변수: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

이 값을 설정하려면 구성을 사용하거나 UseSetting을 호출합니다.

webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_Port

HTTPS 리디렉션 포트. HTTPS 적용에 사용됩니다.

: https_port
형식: string
기본값: 기본값은 설정되지 않습니다.
환경 변수: <PREFIX_>HTTPS_PORT

이 값을 설정하려면 구성을 사용하거나 UseSetting을 호출합니다.

webBuilder.UseSetting("https_port", "8080");

PreferHostingUrls

호스트가 IServer 구현으로 구성된 URL 대신에 IWebHostBuilder로 구성된 URL에서 수신 대기할지 아닌지를 나타냅니다.

: preferHostingUrls
형식: bool(true 또는 1)
기본: true
환경 변수: <PREFIX_>_PREFERHOSTINGURLS

이 값을 설정하려면 환경 변수를 사용하거나 PreferHostingUrls를 호출합니다.

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

앱의 어셈블리에 의해 구성된 호스팅 시작 어셈블리를 포함한 호스팅 시작 어셈블리의 자동 로딩을 방지합니다. 자세한 내용은 ASP.NET Core에서 호스팅 시작 어셈블리 사용를 참조하세요.

: preventHostingStartup
형식: bool(true 또는 1)
기본: false
환경 변수: <PREFIX_>_PREVENTHOSTINGSTARTUP

이 값을 설정하려면 환경 변수를 사용하거나 UseSetting을 호출합니다.

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssembly

Startup 클래스를 검색할 어셈블리입니다.

: startupAssembly
형식: string
기본값: 앱의 어셈블리
환경 변수: <PREFIX_>STARTUPASSEMBLY

이 값을 설정하려면 환경 변수를 사용하거나 UseStartup을 호출합니다. UseStartup은 어셈블리 이름(string) 또는 형식(TStartup)을 사용할 수 있습니다. UseStartup 메서드가 여러 개 호출된 경우 마지막 메서드가 우선 적용됩니다.

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

URL

서버에서 요청을 수신해야 하는 포트와 프로토콜을 포함하는 세미클론으로 구분된 IP 주소 또는 호스트 주소의 목록입니다. 예: http://localhost:123. “*”를 사용하여 서버가 지정된 포트 및 프로토콜을 사용하는 IP 주소 또는 호스트 이름에서 요청을 수신해야 함을 나타냅니다(예: http://*:5000). 프로토콜(http:// 또는 https://)은 각 URL에 포함되어 있어야 합니다. 지원되는 형식은 서버마다 다릅니다.

: urls
형식: string
기본값: http://localhost:5000https://localhost:5001
환경 변수: <PREFIX_>URLS

이 값을 설정하려면 환경 변수를 사용하거나 UseUrls를 호출합니다.

webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");

Kestrel에는 자체 엔드포인트 구성 API가 있습니다. 자세한 내용은 ASP.NET Core Kestrel 웹 서버의 엔드포인트 구성를 참조하세요.

WebRoot

IWebHostEnvironment.WebRootPath 속성은 앱 정적 자산의 상대 경로를 결정합니다. 경로가 존재하지 않으면 no-op 파일 공급자가 사용됩니다.

: webroot
형식: string
기본값: 기본값은 wwwroot입니다. {content root}/wwwroot 경로가 존재해야 합니다.
환경 변수: <PREFIX_>WEBROOT

이 값을 설정하려면 환경 변수를 사용하거나 IWebHostBuilder에서 UseWebRoot를 호출합니다.

webBuilder.UseWebRoot("public");

자세한 내용은 다음을 참조하세요.

호스트 수명 관리

기본 제공된 IHost 구현에 대한 메서드를 호출하여 애플리케이션을 시작하고 중지합니다. 이러한 메서드는 서비스 컨테이너에 등록된 모든 IHostedService 구현에 영향을 줍니다.

Run

Run은 앱을 시작하고 호스트가 종료될 때까지 호출 스레드를 차단합니다.

RunAsync

RunAsync는 앱을 실행하고 취소 토큰 또는 종료가 트리거될 때 완료되는 Task를 반환합니다.

RunConsoleAsync

RunConsoleAsync는 콘솔을 지원하고 호스트를 빌드 및 시작하며 Ctrl+C/SIGINT 또는 SIGTERM이 종료될 때까지 기다립니다.

Start

Start는 호스트를 동기적으로 시작합니다.

StartAsync

StartAsync는 호스트를 시작하고 취소 토큰 또는 종료가 트리거될 때 완료되는 Task를 반환합니다.

WaitForStartAsyncStartAsync의 시작 시 호출되고, 완료될 때까지 기다린 후 계속합니다. 이는 외부 이벤트에서 신호를 보낼 때까지 시작을 지연시키는 데 사용할 수 있습니다.

StopAsync

StopAsync는 지정된 시간 제한 내에서 호스트를 중지하려고 합니다.

WaitForShutdown

WaitForShutdownCtrl+C/SIGINT 또는 SIGTERM을 통해 IHostLifetime에 의해 종료가 트리거될 때까지 호출 스레드를 차단합니다.

WaitForShutdownAsync

WaitForShutdownAsync는 지정된 토큰을 통해 종료가 트리거될 때 완료되는 Task를 반환하고 StopAsync를 호출합니다.

외부 제어

호스트 수명에 대한 직접 제어는 외부에서 호출할 수 있는 메서드를 사용하여 달성할 수 있습니다.

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

ASP.NET Core 템플릿은 .NET Core 일반 호스트(HostBuilder)를 만듭니다.

이 항목에서는 ASP.NET Core에서 .NET 일반 호스트를 사용하는 방법에 관한 정보를 제공합니다. 콘솔 앱에서 .NET 일반 호스트를 사용하는 방법에 관한 자세한 내용은 .NET 일반 호스트를 참조하세요.

호스트 정의

호스트 는 다음과 같이 앱의 리소스를 캡슐화하는 개체입니다.

  • DI(종속성 주입)
  • 로깅
  • Configuration
  • IHostedService 구현

호스트가 시작될 때 서비스 컨테이너의 호스티드 서비스 컬렉션에 등록된 IHostedService의 각 구현에서 IHostedService.StartAsync을 호출합니다. 웹앱에서 IHostedService 구현 중 하나는 HTTP 서버 구현을 시작하는 웹 서비스입니다.

하나의 개체에 앱의 모든 상호 종속적 리소스를 포함하는 주요 원인은 수명 관리 즉, 앱 시작 및 종료에 대한 제어 때문입니다.

호스트 설정

호스트는 일반적으로 Program 클래스의 코드로 구성, 빌드 및 실행됩니다. Main 메서드는 다음 작업을 수행합니다.

  • CreateHostBuilder 메서드를 호출하여 작성기 개체를 만들고 구성합니다.
  • 작성기 개체에서 BuildRun 메서드를 호출합니다.

ASP.NET Core 웹 템플릿은 다음과 같은 코드를 생성하여 일반 호스트를 만듭니다.

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>();
            });
}

다음 코드는 비 HTTP 워크로드를 사용하여 일반 호스트를 만듭니다. IHostedService 구현은 DI 컨테이너에 추가됩니다.

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

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureServices((hostContext, services) =>
            {
               services.AddHostedService<Worker>();
            });
}

HTTP 워크로드의 경우 Main 메서드는 동일하지만 CreateHostBuilderConfigureWebHostDefaults를 호출합니다.

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

위의 코드는 ASP.NET Core 템플릿에서 생성됩니다.

앱에서 Entity Framework Core를 사용하는 경우 CreateHostBuilder 메서드의 이름이나 서명을 변경하지 마세요. Entity Framework Core 도구는 앱을 실행하지 않고 호스트를 구성하는 CreateHostBuilder 메서드를 찾으려고 합니다. 자세한 내용은 디자인 타임 DbContext 만들기를 참조하세요.

기본 작성기 설정

CreateDefaultBuilder 메서드는 다음 작업을 수행합니다.

  • 콘텐츠 루트GetCurrentDirectory에서 반환된 경로로 설정합니다.
  • 다음에서 호스트 구성을 로드합니다.
    • 접두사가 DOTNET_인 환경 변수.
    • 명령줄 인수.
  • 다음에서 앱 구성을 로드합니다.
    • appsettings.json.
    • appsettings.{Environment}.json.
    • 사용자 비밀 - 앱이 Development 환경에서 실행되는 경우.
    • 환경 변수.
    • 명령줄 인수.
  • 다음 로깅 공급자를 추가합니다.
    • Console
    • Debug
    • EventSource
    • EventLog(Windows에서 실행 중인 경우에만)
  • 환경이 개발 중일 때 범위 유효성 검사종속성 유효성 검사를 사용하도록 설정합니다.

ConfigureWebHostDefaults 메서드는 다음 작업을 수행합니다.

이 문서 뒷부분의 모든 앱 유형에 대한 설정웹앱 설정 섹션에서는 기본 작성기 설정을 재정의하는 방법을 보여줍니다.

프레임워크에서 제공하는 서비스

다음 서비스가 자동으로 등록됩니다.

프레임워크에서 제공하는 서비스에 대한 자세한 내용은 ASP.NET Core에서 종속성 주입를 참조하세요.

IHostApplicationLifetime

IHostApplicationLifetime(이전의 IApplicationLifetime) 서비스를 모든 클래스에 삽입하여 사후 시작 및 정상 종료 작업을 처리합니다. 인터페이스의 세 가지 속성은 앱 시작 및 앱 중지 이벤트 처리기 메서드를 등록하는 데 사용되는 취소 토큰입니다. 인터페이스에는 StopApplication 메서드도 포함됩니다.

다음 예제는 IHostApplicationLifetime 이벤트를 등록하는 IHostedService 구현입니다.

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IHostApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IHostApplicationLifetime appLifetime)
    {
        _logger = logger;
        _appLifetime = appLifetime;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _appLifetime.ApplicationStarted.Register(OnStarted);
        _appLifetime.ApplicationStopping.Register(OnStopping);
        _appLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    private void OnStarted()
    {
        _logger.LogInformation("OnStarted has been called.");

        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        _logger.LogInformation("OnStopping has been called.");

        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        _logger.LogInformation("OnStopped has been called.");

        // Perform post-stopped activities here
    }
}

IHostLifetime

IHostLifetime 구현은 호스트가 시작될 때와 중지될 때를 제어합니다. 등록된 마지막 구현이 사용됩니다.

Microsoft.Extensions.Hosting.Internal.ConsoleLifetime은 기본 IHostLifetime 구현입니다. ConsoleLifetime:

IHostEnvironment

IHostEnvironment 서비스를 클래스에 삽입하여 다음 설정에 대한 정보를 가져옵니다.

웹앱은 IHostEnvironment를 상속하고 WebRootPath를 추가하는 IWebHostEnvironment 인터페이스를 구현합니다.

호스트 구성

호스트 구성은 IHostEnvironment 구현의 속성에 사용됩니다.

호스트 구성은 ConfigureAppConfiguration 내부에 HostBuilderContext.Configuration에서 사용할 수 있습니다. ConfigureAppConfiguration 다음에 HostBuilderContext.Configuration이 앱 구성으로 대체됩니다.

호스트 구성을 추가하려면 IHostBuilder에서 ConfigureHostConfiguration을 호출합니다. ConfigureHostConfiguration 항목은 부가적 결과와 함께 여러 번 호출할 수 있습니다. 호스트는 지정된 키에 마지막으로 값을 설정하는 옵션을 사용합니다.

접두사 DOTNET_ 및 명령줄 인수가 있는 환경 변수 공급자는 CreateDefaultBuilder에 포함되어 있습니다. 웹앱의 경우 접두사 ASPNETCORE_가 있는 환경 변수 공급자가 추가됩니다. 접두사는 환경 변수를 읽을 때 제거됩니다. 예를 들어 ASPNETCORE_ENVIRONMENT의 환경 변수 값이 environment 키에 대한 호스트 구성 값이 됩니다.

다음 예제에서는 호스트 구성을 만듭니다.

// using Microsoft.Extensions.Configuration;

Host.CreateDefaultBuilder(args)
    .ConfigureHostConfiguration(configHost =>
    {
        configHost.SetBasePath(Directory.GetCurrentDirectory());
        configHost.AddJsonFile("hostsettings.json", optional: true);
        configHost.AddEnvironmentVariables(prefix: "PREFIX_");
        configHost.AddCommandLine(args);
    });

앱 구성

앱 구성은 IHostBuilder에서 ConfigureAppConfiguration을 호출하여 생성됩니다. ConfigureAppConfiguration 항목은 부가적 결과와 함께 여러 번 호출할 수 있습니다. 앱은 지정된 키에 마지막으로 값을 설정하는 옵션을 사용합니다.

ConfigureAppConfiguration에 의해 생성된 구성은 다음 작업을 위해 HostBuilderContext.Configuration에서 사용 가능하거나 DI의 서비스로 사용할 수 있습니다. 호스트 구성도 앱 구성에 추가됩니다.

자세한 내용은 ASP.NET Core의 구성을 참조하세요.

모든 앱 유형에 대한 설정

이 섹션에는 HTTP 및 비 HTTP 워크로드 모두에 적용되는 호스트 설정이 나열되어 있습니다. 기본적으로 이러한 설정을 구성하는 데 사용되는 환경 변수에는 DOTNET_ 또는 ASPNETCORE_ 접두사가 있을 수 있습니다.

ApplicationName

호스트를 생성하는 동안 호스트 구성에서 IHostEnvironment.ApplicationName 속성을 설정합니다.

: applicationName
형식: string
기본값: 앱의 진입점을 포함하는 어셈블리의 이름입니다.
환경 변수: <PREFIX_>APPLICATIONNAME

이 값을 설정하려면 환경 변수를 사용합니다.

ContentRoot

IHostEnvironment.ContentRootPath 속성은 콘텐츠 파일 검색을 시작하는 위치를 결정합니다. 경로가 존재하지 않는 경우 호스트가 시작되지 않습니다.

: contentRoot
형식: string
기본값: 앱 어셈블리가 있는 폴더입니다.
환경 변수: <PREFIX_>CONTENTROOT

이 값을 설정하려면 환경 변수를 사용하거나 IHostBuilder에서 UseContentRoot를 호출합니다.

Host.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\content-root")
    //...

자세한 내용은 다음을 참조하세요.

EnvironmentName

IHostEnvironment.EnvironmentName 속성을 임의의 값으로 설정할 수 있습니다. 프레임워크에서 정의된 값은 Development, StagingProduction을 포함합니다. 값은 대/소문자를 구분하지 않습니다.

: environment
형식: string
기본: Production
환경 변수: <PREFIX_>ENVIRONMENT

이 값을 설정하려면 환경 변수를 사용하거나 IHostBuilder에서 UseEnvironment를 호출합니다.

Host.CreateDefaultBuilder(args)
    .UseEnvironment("Development")
    //...

ShutdownTimeout

HostOptions.ShutdownTimeoutStopAsync에 대한 시간 제한을 설정합니다. 기본값은 5초입니다. 시간 제한 기간 동안 호스트는 다음을 수행합니다.

모든 호스팅된 서비스가 중지하기 전에 시간 제한 기간이 만료되면 앱이 종료될 때 모든 활성화된 나머지 서비스가 중지됩니다. 처리를 완료하지 않은 경우에도 서비스가 중지됩니다. 서비스를 중지하는 데 시간이 더 필요한 경우 시간 제한을 늘립니다.

: shutdownTimeoutSeconds
형식: int
기본값: 5초
환경 변수: <PREFIX_>SHUTDOWNTIMEOUTSECONDS

이 값을 설정하려면 환경 변수를 사용하거나 HostOptions를 구성합니다. 다음 예제에서는 시간 제한을 20초로 설정합니다.

Host.CreateDefaultBuilder(args)
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    });

웹앱 설정

일부 호스트 설정은 HTTP 워크로드에만 적용됩니다. 기본적으로 이러한 설정을 구성하는 데 사용되는 환경 변수에는 DOTNET_ 또는 ASPNETCORE_ 접두사가 있을 수 있습니다.

이러한 설정에 대해 IWebHostBuilder의 확장 메서드를 사용할 수 있습니다. 확장 메서드를 호출하는 방법을 보여주는 코드 샘플은 다음 예제와 같이 webBuilderIWebHostBuilder의 인스턴스라고 가정합니다.

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

CaptureStartupErrors

false인 경우 시작 시 오류가 발생하면 호스트가 종료됩니다. true이면 호스트가 시작 시 예외를 캡처하고 서버 시작을 시도합니다.

: captureStartupErrors
형식: bool(true 또는 1)
기본값: 기본값이 true인 IIS 뒤에 있는 Kestrel으로 앱이 실행하지 않는 한 기본값은 false로 지정됩니다.
환경 변수: <PREFIX_>CAPTURESTARTUPERRORS

이 값을 설정하려면 구성을 사용하거나 CaptureStartupErrors를 호출합니다.

webBuilder.CaptureStartupErrors(true);

DetailedErrors

활성화하거나 환경이 Development인 경우 앱은 자세한 오류를 캡처합니다.

: detailedErrors
형식: bool(true 또는 1)
기본: false
환경 변수: <PREFIX_>_DETAILEDERRORS

이 값을 설정하려면 구성을 사용하거나 UseSetting을 호출합니다.

webBuilder.UseSetting(WebHostDefaults.DetailedErrorsKey, "true");

HostingStartupAssemblies

시작 시 로드할 호스팅 시작 어셈블리의 세미콜론으로 구분된 문자열입니다. 구성 값의 기본값이 빈 문자열이지만, 호스팅 시작 어셈블리는 항상 앱의 어셈블리를 포함합니다. 호스팅 시작 어셈블리가 제공되는 경우, 시작 시 앱이 일반적인 서비스를 빌드할 때 로드를 위해 앱의 어셈블리에 추가됩니다.

: hostingStartupAssemblies
형식: string
기본값: 빈 문자열
환경 변수: <PREFIX_>_HOSTINGSTARTUPASSEMBLIES

이 값을 설정하려면 구성을 사용하거나 UseSetting을 호출합니다.

webBuilder.UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2");

HostingStartupExcludeAssemblies

시작 시 제외할 호스팅 시작 어셈블리의 세미콜론으로 구분된 문자열입니다.

: hostingStartupExcludeAssemblies
형식: string
기본값: 빈 문자열
환경 변수: <PREFIX_>_HOSTINGSTARTUPEXCLUDEASSEMBLIES

이 값을 설정하려면 구성을 사용하거나 UseSetting을 호출합니다.

webBuilder.UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2");

HTTPS_Port

HTTPS 리디렉션 포트. HTTPS 적용에 사용됩니다.

: https_port
형식: string
기본값: 기본값은 설정되지 않습니다.
환경 변수: <PREFIX_>HTTPS_PORT

이 값을 설정하려면 구성을 사용하거나 UseSetting을 호출합니다.

webBuilder.UseSetting("https_port", "8080");

PreferHostingUrls

호스트가 IServer 구현으로 구성된 URL 대신에 IWebHostBuilder로 구성된 URL에서 수신 대기할지 아닌지를 나타냅니다.

: preferHostingUrls
형식: bool(true 또는 1)
기본: true
환경 변수: <PREFIX_>_PREFERHOSTINGURLS

이 값을 설정하려면 환경 변수를 사용하거나 PreferHostingUrls를 호출합니다.

webBuilder.PreferHostingUrls(false);

PreventHostingStartup

앱의 어셈블리에 의해 구성된 호스팅 시작 어셈블리를 포함한 호스팅 시작 어셈블리의 자동 로딩을 방지합니다. 자세한 내용은 ASP.NET Core에서 호스팅 시작 어셈블리 사용를 참조하세요.

: preventHostingStartup
형식: bool(true 또는 1)
기본: false
환경 변수: <PREFIX_>_PREVENTHOSTINGSTARTUP

이 값을 설정하려면 환경 변수를 사용하거나 UseSetting을 호출합니다.

webBuilder.UseSetting(WebHostDefaults.PreventHostingStartupKey, "true");

StartupAssembly

Startup 클래스를 검색할 어셈블리입니다.

: startupAssembly
형식: string
기본값: 앱의 어셈블리
환경 변수: <PREFIX_>STARTUPASSEMBLY

이 값을 설정하려면 환경 변수를 사용하거나 UseStartup을 호출합니다. UseStartup은 어셈블리 이름(string) 또는 형식(TStartup)을 사용할 수 있습니다. UseStartup 메서드가 여러 개 호출된 경우 마지막 메서드가 우선 적용됩니다.

webBuilder.UseStartup("StartupAssemblyName");
webBuilder.UseStartup<Startup>();

URL

서버에서 요청을 수신해야 하는 포트와 프로토콜을 포함하는 세미클론으로 구분된 IP 주소 또는 호스트 주소의 목록입니다. 예: http://localhost:123. “*”를 사용하여 서버가 지정된 포트 및 프로토콜을 사용하는 IP 주소 또는 호스트 이름에서 요청을 수신해야 함을 나타냅니다(예: http://*:5000). 프로토콜(http:// 또는 https://)은 각 URL에 포함되어 있어야 합니다. 지원되는 형식은 서버마다 다릅니다.

: urls
형식: string
기본값: http://localhost:5000https://localhost:5001
환경 변수: <PREFIX_>URLS

이 값을 설정하려면 환경 변수를 사용하거나 UseUrls를 호출합니다.

webBuilder.UseUrls("http://*:5000;http://localhost:5001;https://hostname:5002");

Kestrel에는 자체 엔드포인트 구성 API가 있습니다. 자세한 내용은 ASP.NET Core에서 Kestrel 웹 서버 구현를 참조하세요.

WebRoot

IWebHostEnvironment.WebRootPath 속성은 앱 정적 자산의 상대 경로를 결정합니다. 경로가 존재하지 않으면 no-op 파일 공급자가 사용됩니다.

: webroot
형식: string
기본값: 기본값은 wwwroot입니다. {content root}/wwwroot 경로가 존재해야 합니다.
환경 변수: <PREFIX_>WEBROOT

이 값을 설정하려면 환경 변수를 사용하거나 IWebHostBuilder에서 UseWebRoot를 호출합니다.

webBuilder.UseWebRoot("public");

자세한 내용은 다음을 참조하세요.

호스트 수명 관리

기본 제공된 IHost 구현에 대한 메서드를 호출하여 애플리케이션을 시작하고 중지합니다. 이러한 메서드는 서비스 컨테이너에 등록된 모든 IHostedService 구현에 영향을 줍니다.

Run

Run은 앱을 시작하고 호스트가 종료될 때까지 호출 스레드를 차단합니다.

RunAsync

RunAsync는 앱을 실행하고 취소 토큰 또는 종료가 트리거될 때 완료되는 Task를 반환합니다.

RunConsoleAsync

RunConsoleAsync는 콘솔을 지원하고 호스트를 빌드 및 시작하며 Ctrl+C/SIGINT 또는 SIGTERM이 종료될 때까지 기다립니다.

Start

Start는 호스트를 동기적으로 시작합니다.

StartAsync

StartAsync는 호스트를 시작하고 취소 토큰 또는 종료가 트리거될 때 완료되는 Task를 반환합니다.

WaitForStartAsyncStartAsync의 시작 시 호출되고, 완료될 때까지 기다린 후 계속합니다. 이는 외부 이벤트에서 신호를 보낼 때까지 시작을 지연시키는 데 사용할 수 있습니다.

StopAsync

StopAsync는 지정된 시간 제한 내에서 호스트를 중지하려고 합니다.

WaitForShutdown

WaitForShutdownCtrl+C/SIGINT 또는 SIGTERM을 통해 IHostLifetime에 의해 종료가 트리거될 때까지 호출 스레드를 차단합니다.

WaitForShutdownAsync

WaitForShutdownAsync는 지정된 토큰을 통해 종료가 트리거될 때 완료되는 Task를 반환하고 StopAsync를 호출합니다.

외부 제어

호스트 수명에 대한 직접 제어는 외부에서 호출할 수 있는 메서드를 사용하여 달성할 수 있습니다.

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

ASP.NET Core 앱은 호스트를 구성 및 실행합니다. 호스트는 앱 시작 및 수명 관리를 담당합니다.

이 문서에서는 HTTP 요청을 처리하지 않는 앱에 사용되는 ASP.NET Core 일반 호스트(HostBuilder)를 다룹니다.

일반 호스트의 목적은 웹 호스트 API에서 HTTP 파이프라인을 분리하여 호스트 시나리오의 더 광범위한 배열을 구현하는 것입니다. 일반 호스트에 기반을 둔 메시징, 백그라운드 작업 및 기타 HTTP 이외 워크로드는 구성, DI(종속성 주입) 및 로깅과 같은 교차 편집 기능에서 이점을 얻습니다.

일반 호스트는 ASP.NET Core 2.1의 새로운 기능이며 웹 호스팅 시나리오에 적합하지 않습니다. 웹 호스팅 시나리오의 경우 웹 호스트를 사용하세요. 일반 호스트는 향후 릴리스에서 웹 호스트를 대체하고 HTTP 및 HTTP 이외 시나리오에서 기본 호스트 API 역할을 합니다.

예제 코드 살펴보기 및 다운로드 (다운로드 방법)

Visual Studio Code에서 샘플 앱을 실행할 때는 외부 또는 통합 터미널 을 사용하세요. internalConsole에서는 샘플을 실행하지 마세요.

Visual Studio Code에서 콘솔을 설정하려면:

  1. .vscode/launch.json 파일을 엽니다.
  2. .NET Core 시작(콘솔) 구성에서 콘솔 항목을 찾습니다. 값을 externalTerminal 또는 integratedTerminal 중 하나로 설정합니다.

소개

일반 호스트 라이브러리는 Microsoft.Extensions.Hosting 네임스페이스에서 사용할 수 있으며, Microsoft.Extensions.Hosting 패키지에서 제공합니다. Microsoft.Extensions.Hosting 패키지는 Microsoft.AspNetCore.App 메타패키지(ASP.NET Core 2.1 이상)에 포함되어 있습니다.

IHostedService는 코드 실행 진입점입니다. 각 IHostedService 구현은 ConfigureServices의 서비스 등록 순서대로 실행됩니다. StartAsync는 호스트가 시작될 때 각 IHostedService에서 호출되고, StopAsync는 호스트가 점진적으로 종료될 때 등록 순서의 역순으로 호출됩니다.

호스트 설정

IHostBuilder는 라이브러리 및 앱이 호스트를 초기화, 빌드 및 실행하는 데 사용하는 주 구성 요소입니다.

public static async Task Main(string[] args)
{
    var host = new HostBuilder()
        .Build();

    await host.RunAsync();
}

옵션

HostOptionsIHost에 대한 옵션을 구성합니다.

시스템 종료 시간 제한

ShutdownTimeoutStopAsync에 대한 시간 제한을 설정합니다. 기본값은 5초입니다.

Program.Main의 다음 옵션 구성은 기본 5초 시스템 종료 시간 제한을 20초로 늘립니다.

var host = new HostBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        services.Configure<HostOptions>(option =>
        {
            option.ShutdownTimeout = System.TimeSpan.FromSeconds(20);
        });
    })
    .Build();

기본 서비스

호스트 초기화 중에 다음 서비스가 등록됩니다.

호스트 구성

호스트 구성은 다음에 의해 만들어집니다.

확장 메서드

애플리케이션 키(이름)

호스트를 생성하는 동안 호스트 구성에서 IHostingEnvironment.ApplicationName 속성을 설정합니다. 값을 명시적으로 설정하려면 HostDefaults.ApplicationKey를 사용합니다.

: applicationName
형식: string
기본값: 앱의 진입점을 포함하는 어셈블리의 이름입니다.
설정 방법: HostBuilderContext.HostingEnvironment.ApplicationName
환경 변수: <PREFIX_>APPLICATIONNAME(<PREFIX_>선택적이고 사용자 정의됨)

콘텐츠 루트

이 설정은 호스트가 콘텐츠 파일을 검색하기 시작하는 지점을 결정합니다.

: contentRoot
형식: string
기본값: 앱 어셈블리가 있는 폴더가 기본값으로 지정됩니다.
설정 방법: UseContentRoot
환경 변수: <PREFIX_>CONTENTROOT(<PREFIX_>선택적이고 사용자 정의됨)

경로가 존재하지 않는 경우 호스트가 시작되지 않습니다.

var host = new HostBuilder()
    .UseContentRoot("c:\\<content-root>")

자세한 내용은 기본 사항: 콘텐츠 루트를 참조하세요.

환경

앱의 환경을 설정합니다.

: environment
형식: string
기본: Production
설정 방법: UseEnvironment
환경 변수: <PREFIX_>ENVIRONMENT(<PREFIX_>선택적이고 사용자 정의됨)

환경은 어떠한 값으로도 설정할 수 있습니다. 프레임워크에서 정의된 값은 Development, StagingProduction을 포함합니다. 값은 대/소문자를 구분하지 않습니다.

var host = new HostBuilder()
    .UseEnvironment(EnvironmentName.Development)

ConfigureHostConfiguration

ConfigureHostConfigurationIConfigurationBuilder를 사용하여 호스트에 대한 IConfiguration을 만듭니다. 호스트 구성은 앱의 빌드 프로세스에 사용할 IHostingEnvironment를 초기화하는 데 사용됩니다.

ConfigureHostConfiguration 항목은 부가적 결과와 함께 여러 번 호출할 수 있습니다. 호스트는 지정된 키에 마지막으로 값을 설정하는 옵션을 사용합니다.

기본적으로 공급자는 포함되지 않습니다. 다음을 포함하여 앱에 필요한 모든 구성 공급자를 ConfigureHostConfiguration에 명시적으로 지정해야 합니다.

  • 구성 파일(예: hostsettings.json 파일에서).
  • 환경 변수 구성.
  • 명령줄 인수 구성.
  • 기타 필수 구성 공급자.

호스트의 파일 구성은 SetBasePath를 사용하여 앱의 기본 경로를 지정한 후 파일 구성 공급자 중 하나를 호출하여 활성화됩니다. 샘플 앱은 JSON 파일인 hostsettings.json 을 사용하고 AddJsonFile을 호출하여 파일의 호스트 구성 설정을 사용합니다.

환경 변수 구성을 추가하려면 호스트 작성기에서 AddEnvironmentVariables를 호출합니다. AddEnvironmentVariables는 선택적 사용자 정의 접두사를 허용합니다. 샘플 앱은 PREFIX_ 접두사를 사용합니다. 접두사는 환경 변수를 읽을 때 제거됩니다. 샘플 앱의 호스트가 구성되면 PREFIX_ENVIRONMENT의 환경 변수 값이 environment 키에 대한 호스트 구성 값이 됩니다.

Visual Studio를 사용하거나 dotnet run을 통해 앱을 실행할 때 개발하는 동안에 환경 변수는 Properties/launchSettings.json 파일에 설정될 수 있습니다. Visual Studio Code에서 환경 변수는 개발하는 동안에 .vscode/launch.json 파일에 설정될 수 있습니다. 자세한 내용은 ASP.NET Core에서 여러 환경 사용를 참조하세요.

명령줄 구성AddCommandLine을 호출하여 추가됩니다. 명령줄 구성이 마지막으로 추가되어 명령줄 인수가 이전 구성 공급자가 제공한 구성을 재정의할 수 있습니다.

hostsettings.json:

{
  "environment": "Development"
}

applicationNamecontentRoot 키를 사용하여 추가 구성을 제공할 수 있습니다.

ConfigureHostConfiguration을 사용한 HostBuilder 구성 예:

var host = new HostBuilder()
    .ConfigureHostConfiguration(configHost =>
    {
        configHost.SetBasePath(Directory.GetCurrentDirectory());
        configHost.AddJsonFile("hostsettings.json", optional: true);
        configHost.AddEnvironmentVariables(prefix: "PREFIX_");
        configHost.AddCommandLine(args);
    })

ConfigureAppConfiguration

앱 구성은 IHostBuilder 구현에서 ConfigureAppConfiguration을 호출하여 생성됩니다. ConfigureAppConfigurationIConfigurationBuilder를 사용하여 앱에 대한 IConfiguration을 만듭니다. ConfigureAppConfiguration 항목은 부가적 결과와 함께 여러 번 호출할 수 있습니다. 앱은 지정된 키에 마지막으로 값을 설정하는 옵션을 사용합니다. ConfigureAppConfiguration에 의해 생성된 구성은 다음 작업에 대한 HostBuilderContext.ConfigurationServices에서 사용할 수 있습니다.

앱 구성은 ConfigureHostConfiguration에서 제공하는 호스트 구성을 자동으로 수신합니다.

ConfigureAppConfiguration을 사용한 앱 구성 예:

var host = new HostBuilder()
    .ConfigureAppConfiguration((hostContext, configApp) =>
    {
        configApp.SetBasePath(Directory.GetCurrentDirectory());
        configApp.AddJsonFile("appsettings.json", optional: true);
        configApp.AddJsonFile(
            $"appsettings.{hostContext.HostingEnvironment.EnvironmentName}.json", 
            optional: true);
        configApp.AddEnvironmentVariables(prefix: "PREFIX_");
        configApp.AddCommandLine(args);
    })

appsettings.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning"
    }
  },
  "AllowedHosts": "*"
}

appsettings.Development.json:

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

appsettings.Production.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Error",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

출력 디렉터리로 설정 파일을 이동하려면, 설정 파일을 프로젝트 파일 내 MSBuild 프로젝트 항목으로 지정합니다. 샘플 앱은 다음 <Content> 항목과 함께 JSON 앱 설정 파일과 hostsettings.json 을 이동합니다.

<ItemGroup>
  <Content Include="**\*.json" Exclude="bin\**\*;obj\**\*" 
      CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

참고

AddJsonFileAddEnvironmentVariables와 같은 구성 확장 메서드에는 Microsoft.Extensions.Configuration.JsonMicrosoft.Extensions.Configuration.EnvironmentVariables와 같은 추가 NuGet 패키지가 필요합니다. 앱에서 Microsoft.AspNetCore.App 메타패키지를 사용하는 경우가 아니면 이 패키지는 코어 Microsoft.Extensions.Configuration 패키지에 추가로 프로젝트에 추가되어야 합니다. 자세한 내용은 ASP.NET Core의 구성를 참조하세요.

ConfigureServices

ConfigureServices는 앱의 종속성 주입 컨테이너에 서비스를 추가합니다. ConfigureServices 항목은 부가적 결과와 함께 여러 번 호출할 수 있습니다.

호스티드 서비스는 IHostedService 인터페이스를 구현하는 백그라운드 작업 논리가 있는 클래스입니다. 자세한 내용은 ASP.NET Core에서 호스팅되는 서비스를 사용하는 백그라운드 작업를 참조하세요.

샘플 앱AddHostedService 확장 메서드를 사용하여 수명 이벤트, LifetimeEventsHostedService 및 시간 제한 백그라운드 작업에 대한 서비스 TimedHostedService를 앱에 추가합니다.

var host = new HostBuilder()
    .ConfigureServices((hostContext, services) =>
    {
        if (hostContext.HostingEnvironment.IsDevelopment())
        {
            // Development service configuration
        }
        else
        {
            // Non-development service configuration
        }

        services.AddHostedService<LifetimeEventsHostedService>();
        services.AddHostedService<TimedHostedService>();
    })

ConfigureLogging

ConfigureLogging에는 제공된 ILoggingBuilder를 구성하는 대리자가 추가됩니다. ConfigureLogging 항목은 부가적 결과와 함께 여러 번 호출할 수 있습니다.

var host = new HostBuilder()
    .ConfigureLogging((hostContext, configLogging) =>
    {
        configLogging.AddConsole();
        configLogging.AddDebug();
    })

UseConsoleLifetime

UseConsoleLifetimeCtrl+C/SIGINT 또는 SIGTERM을 수신 대기하고 StopApplication을 호출하여 종료 프로세스를 시작합니다. UseConsoleLifetimeRunAsyncWaitForShutdownAsync와 같은 확장의 차단을 해제합니다. Microsoft.Extensions.Hosting.Internal.ConsoleLifetime은 기본 수명 구현으로 미리 등록됩니다. 등록된 마지막 수명이 사용됩니다.

var host = new HostBuilder()
    .UseConsoleLifetime()

컨테이너 구성

호스트는 다른 컨테이너 연결을 지원하기 위해 IServiceProviderFactory<TContainerBuilder>를 사용할 수 있습니다. 팩터리 제공은 DI 컨테이너 등록의 일부가 아니지만 구체적 DI 컨테이너를 만드는 데 사용되는 내장 호스트입니다. UseServiceProviderFactory(IServiceProviderFactory<TContainerBuilder>)는 앱의 서비스 공급자를 만드는 데 사용되는 기본 팩터리를 재정의합니다.

사용자 지정 컨테이너 구성은 ConfigureContainer 메서드로 관리됩니다. ConfigureContainer는 기본 호스트 API 위에 컨테이너를 구성하기 위한 강력한 형식의 환경입니다. ConfigureContainer 항목은 부가적 결과와 함께 여러 번 호출할 수 있습니다.

앱에 대한 서비스 컨테이너를 만듭니다.

namespace GenericHostSample
{
    internal class ServiceContainer
    {
    }
}

서비스 컨테이너 팩터리를 제공합니다.

using System;
using Microsoft.Extensions.DependencyInjection;

namespace GenericHostSample
{
    internal class ServiceContainerFactory : 
        IServiceProviderFactory<ServiceContainer>
    {
        public ServiceContainer CreateBuilder(
            IServiceCollection services)
        {
            return new ServiceContainer();
        }

        public IServiceProvider CreateServiceProvider(
            ServiceContainer containerBuilder)
        {
            throw new NotImplementedException();
        }
    }
}

팩터리를 사용하고 앱에 대 한 사용자 지정 서비스 컨테이너를 구성 합니다.

var host = new HostBuilder()
    .UseServiceProviderFactory<ServiceContainer>(new ServiceContainerFactory())
    .ConfigureContainer<ServiceContainer>((hostContext, container) =>
    {
    })

확장성

IHostBuilder에서 확장 메서드를 사용하여 호스트 확장성이 수행됩니다. 다음 예제는 ASP.NET Core에서 호스팅되는 서비스를 사용하는 백그라운드 작업에 설명된 TimedHostedService 예제를 사용하여 확장 메서드가 IHostBuilder 구현을 확장하는 방법을 보여줍니다.

var host = new HostBuilder()
    .UseHostedService<TimedHostedService>()
    .Build();

await host.StartAsync();

앱은 UseHostedService 확장 메서드를 설정하여 T에서 전달되는 호스티드 서비스를 등록합니다.

using System;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

public static class Extensions
{
    public static IHostBuilder UseHostedService<T>(this IHostBuilder hostBuilder)
        where T : class, IHostedService, IDisposable
    {
        return hostBuilder.ConfigureServices(services =>
            services.AddHostedService<T>());
    }
}

호스트 관리

IHost 구현은 서비스 컨테이너에 등록된 IHostedService 구현의 시작 및 중지를 담당합니다.

Run

Run은 앱을 시작하고 호스트가 종료될 때까지 호출 스레드를 차단합니다.

public class Program
{
    public void Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        host.Run();
    }
}

RunAsync

RunAsync는 앱을 실행하고 취소 토큰 또는 종료가 트리거될 때 완료되는 Task를 반환합니다.

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        await host.RunAsync();
    }
}

RunConsoleAsync

RunConsoleAsync는 콘솔을 지원하고 호스트를 빌드 및 시작하며 Ctrl+C/SIGINT 또는 SIGTERM이 종료될 때까지 기다립니다.

public class Program
{
    public static async Task Main(string[] args)
    {
        var hostBuilder = new HostBuilder();

        await hostBuilder.RunConsoleAsync();
    }
}

Start 및 StopAsync

Start는 호스트를 동기적으로 시작합니다.

StopAsync는 지정된 시간 제한 내에서 호스트를 중지하려고 합니다.

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            host.Start();

            await host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

StartAsync 및 StopAsync

StartAsync가 서버를 시작합니다.

StopAsync가 서버를 중지합니다.

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            await host.StartAsync();

            await host.StopAsync();
        }
    }
}

WaitForShutdown

WaitForShutdownMicrosoft.Extensions.Hosting.Internal.ConsoleLifetime(Ctrl+C/SIGINT 또는 SIGTERM 수신 대기)과 같이 IHostLifetime을 통해 트리거됩니다. WaitForShutdownStopAsync를 호출합니다.

public class Program
{
    public void Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            host.Start();

            host.WaitForShutdown();
        }
    }
}

WaitForShutdownAsync

WaitForShutdownAsync는 지정된 토큰을 통해 종료가 트리거될 때 완료되는 Task를 반환하고 StopAsync를 호출합니다.

public class Program
{
    public static async Task Main(string[] args)
    {
        var host = new HostBuilder()
            .Build();

        using (host)
        {
            await host.StartAsync();

            await host.WaitForShutdownAsync();
        }

    }
}

외부 제어

외부에서 호출할 수 있는 메서드를 사용하여 호스트의 외부 제어를 구현할 수 있습니다.

public class Program
{
    private IHost _host;

    public Program()
    {
        _host = new HostBuilder()
            .Build();
    }

    public async Task StartAsync()
    {
        _host.StartAsync();
    }

    public async Task StopAsync()
    {
        using (_host)
        {
            await _host.StopAsync(TimeSpan.FromSeconds(5));
        }
    }
}

WaitForStartAsyncStartAsync의 시작 시 호출되고, 완료될 때까지 기다린 후 계속합니다. 이는 외부 이벤트에서 신호를 보낼 때까지 시작을 지연시키는 데 사용할 수 있습니다.

IHostingEnvironment 인터페이스

IHostingEnvironment는 앱의 호스팅 환경에 대한 정보를 제공합니다. 해당 속성 및 확장 메서드를 사용하기 위해 생성자 주입을 사용하여 IHostingEnvironment를 가져옵니다.

public class MyClass
{
    private readonly IHostingEnvironment _env;

    public MyClass(IHostingEnvironment env)
    {
        _env = env;
    }

    public void DoSomething()
    {
        var environmentName = _env.EnvironmentName;
    }
}

자세한 내용은 ASP.NET Core에서 여러 환경 사용를 참조하세요.

IApplicationLifetime 인터페이스

IApplicationLifetime은 점진적인 종료 요청을 비롯한 사후 시작 및 종료 작업을 고려합니다. 인터페이스에서 세 가지 속성은 취소 토큰으로, 시작 및 종료 이벤트를 정의하는 Action 메서드를 등록하는 데 사용됩니다.

취소 토큰 트리거되는 경우:
ApplicationStarted 호스트가 완벽하게 시작되었습니다.
ApplicationStopped 호스트가 정상적으로 종료되었습니다. 모든 요청이 처리되어야 합니다. 종료는 이 이벤트가 완료될 때까지 차단합니다.
ApplicationStopping 호스트가 정상적으로 종료되고 있습니다. 요청은 계속 처리할 수 있습니다. 종료는 이 이벤트가 완료될 때까지 차단합니다.

클래스에 대한 IApplicationLifetime 서비스 생성자 주입을 수행합니다. 샘플 앱LifetimeEventsHostedService 클래스(IHostedService 구현)에 대한 생성자 주입을 사용하여 이벤트를 등록합니다.

LifetimeEventsHostedService.cs:

internal class LifetimeEventsHostedService : IHostedService
{
    private readonly ILogger _logger;
    private readonly IApplicationLifetime _appLifetime;

    public LifetimeEventsHostedService(
        ILogger<LifetimeEventsHostedService> logger, 
        IApplicationLifetime appLifetime)
    {
        _logger = logger;
        _appLifetime = appLifetime;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _appLifetime.ApplicationStarted.Register(OnStarted);
        _appLifetime.ApplicationStopping.Register(OnStopping);
        _appLifetime.ApplicationStopped.Register(OnStopped);

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    private void OnStarted()
    {
        _logger.LogInformation("OnStarted has been called.");

        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        _logger.LogInformation("OnStopping has been called.");

        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        _logger.LogInformation("OnStopped has been called.");

        // Perform post-stopped activities here
    }
}

StopApplication은 앱의 종료를 요청합니다. 다음 클래스에서는 StopApplication을 사용하여 해당 클래스의 Shutdown 메서드를 호출하는 경우 앱을 정상 종료합니다.

public class MyClass
{
    private readonly IApplicationLifetime _appLifetime;

    public MyClass(IApplicationLifetime appLifetime)
    {
        _appLifetime = appLifetime;
    }

    public void Shutdown()
    {
        _appLifetime.StopApplication();
    }
}

추가 리소스

  • ASP.NET Core에서 호스팅되는 서비스를 사용하는 백그라운드 작업
  • 제네릭 호스트 원본 > [!NOTE] > ASP.NET Core 참조 원본에 대한 설명서 링크는 ASP.NET Core의 다음 릴리스를 위한 제품 단위의 현재 개발을 나타내는 리포지토리의 main 분기를 로드합니다. 다른 릴리스에 대한 분기를 선택하려면 Switch branches or tags(분기 또는 태그 전환) 드롭다운 목록을 사용하여 분기를 선택합니다. 예를 들어 release/5.0 ASP.NET Core 5.0 릴리스에 대한 분기를 선택합니다.에 대한 GitHub 링크