다음을 통해 공유

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

  • 아티클

참고 항목

이 문서의 최신 버전은 아닙니다. 현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

Warning

이 버전의 ASP.NET Core는 더 이상 지원되지 않습니다. 자세한 내용은 .NET 및 .NET Core 지원 정책을 참조 하세요. 현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

Important

이 정보는 상업적으로 출시되기 전에 실질적으로 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적, 또는 묵시적인 보증을 하지 않습니다.

현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

이 문서에서는 ASP.NET Core에서 .NET 제네릭 호스트를 사용하는 방법에 관한 정보를 제공합니다.

ASP.NET Core 템플릿은 Startup 클래스 없이 웹 애플리케이션을 구성하고 실행하는 간소화된 방법을 제공하는 WebApplicationBuilder 및 WebApplication을 만듭니다. WebApplicationBuilder 및 WebApplication에 대한 자세한 내용은 ASP.NET Core 5.0에서 6.0으로 마이그레이션을 참조하세요.

콘솔 앱에서 .NET 제네릭 호스트를 사용하는 방법에 관한 자세한 내용은 .NET 제네릭 호스트를 참조하세요.

호스트 정의

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

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

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

하나의 개체에 앱의 상호 종속적인 리소스를 모두 포함하면 앱 시작 및 정상 종료를 제어할 수 있습니다.

호스트 설정

호스트는 일반적으로 Program.cs의 코드로 구성, 빌드 및 실행됩니다. 다음 코드는 DI 컨테이너에 IHostedService 구현이 추가된 호스트를 만듭니다.

await Host.CreateDefaultBuilder(args)
    .ConfigureServices(services =>
    {
        services.AddHostedService<SampleHostedService>();
    })
    .Build()
    .RunAsync();

HTTP 워크로드의 경우 CreateDefaultBuilder 다음에 ConfigureWebHostDefaults를 호출합니다.

await Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    })
    .Build()
    .RunAsync();

기본 작성기 설정

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

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

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

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

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

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

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

IHostApplicationLifetime

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

정상 종료 시 호스트는 다음 작업을 수행합니다.

  • 종료 프로세스가 시작되기 전에 앱에서 논리를 실행할 수 있도록 하는 ApplicationStopping 이벤트 처리기를 트리거합니다.
  • 서버를 중지하여 새 연결을 차단합니다. 종료 제한 시간이 허용하는 한 서버가 기존 연결에 대한 요청이 완료되기를 기다립니다. 서버는 기존 연결에 대한 추가 요청에 대해 연결 닫기 헤더를 보냅니다.
  • 애플리케이션이 종료된 후 앱이 논리를 실행할 수 있도록 하는 ApplicationStopped 이벤트 처리기를 트리거합니다.

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

public class HostApplicationLifetimeEventsHostedService : IHostedService
{
    private readonly IHostApplicationLifetime _hostApplicationLifetime;

    public HostApplicationLifetimeEventsHostedService(
        IHostApplicationLifetime hostApplicationLifetime)
        => _hostApplicationLifetime = hostApplicationLifetime;

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

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
        => Task.CompletedTask;

    private void OnStarted()
    {
        // ...
    }

    private void OnStopping()
    {
        // ...
    }

    private void OnStopped()
    {
        // ...
    }
}

IHostLifetime

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

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

  • Ctrl+C/SIGINT(Windows), ⌘+C(macOS) 또는 SIGTERM을 수신 대기하고 StopApplication을 트리거하여 종료 프로세스를 시작합니다.
  • RunAsync 및 WaitForShutdownAsync와 같은 확장의 차단을 해제합니다.

IHostEnvironment

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

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

호스트 구성

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

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

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

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

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

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

앱 구성

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

ConfigureAppConfiguration에 의해 생성된 구성은 후속 작업을 위해 HostBuilderContext.Configuration에서 사용할 수 있고 또한 DI의 서비스로 사용할 수 있습니다. 호스트 구성도 앱 구성에 추가됩니다.

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

모든 앱 유형에 대한 설정

이 섹션에는 HTTP 및 비 HTTP 워크로드 모두에 적용되는 호스트 설정이 나열되어 있습니다. 기본적으로 이러한 설정을 구성하는 데 사용되는 환경 변수에는 DOTNET_ 또는 ASPNETCORE_ 접두사가 포함될 수 있습니다. 이들은 다음 설정 목록에 {PREFIX_} 자리 표시자로 표시되어 있습니다. 자세한 내용은 기본 작성기 설정 섹션 및 구성: 환경 변수를 참조하세요.

ApplicationName

IHostEnvironment.ApplicationName 속성은 호스트 생성 도중 호스트 구성에서 설정됩니다.

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

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

ContentRoot

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

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

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

Host.CreateDefaultBuilder(args)
    .UseContentRoot("/path/to/content/root")
    // ...

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

EnvironmentName

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

키: environment
형식: string
기본값: Production
환경 변수: {PREFIX_}ENVIRONMENT

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

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

ShutdownTimeout

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

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

키: shutdownTimeoutSeconds
형식: int
기본값: 30초
환경 변수: {PREFIX_}SHUTDOWNTIMEOUTSECONDS

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

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

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

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

키: hostBuilder:reloadConfigOnChange
형식: bool(true 또는 false)
기본값: true
명령줄 인수: hostBuilder:reloadConfigOnChange
환경 변수: {PREFIX_}hostBuilder:reloadConfigOnChange

Warning

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

웹앱 설정

일부 호스트 설정은 HTTP 워크로드에만 적용됩니다. 기본적으로 이러한 설정을 구성하는 데 사용되는 환경 변수에는 DOTNET_ 또는 ASPNETCORE_ 접두사가 포함될 수 있습니다. 이들은 다음 설정 목록에 {PREFIX_} 자리 표시자로 표시되어 있습니다.

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

Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        // ...
    });

CaptureStartupErrors

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

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

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

키: detailedErrors
형식: bool(true/1 또는 false/0)
기본값: 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 적용에 사용됩니다. 이 설정으로 인해 서버가 지정된 포트에서 수신 대기하지 않습니다. 즉, 요청을 사용하지 않는 포트로 실수로 리디렉션할 수 있습니다.

키: 형식: https_portstring
기본값: 기본값이 설정되지 않았습니다.
환경 변수: {PREFIX_}HTTPS_PORT

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

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

HTTPS_Ports

HTTPS 연결을 수신 대기할 포트입니다.

키: https_ports
형식: string
기본값: 기본값이 설정되지 않았습니다.
환경 변수: {PREFIX_}HTTPS_PORTS

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

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

PreferHostingUrls

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

키: preferHostingUrls
형식: bool(true/1 또는 false/0)
기본값: false
환경 변수: {PREFIX_}PREFERHOSTINGURLS

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

키: preventHostingStartup
형식: bool(true/1 또는 false/0)
기본값: 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>();

SuppressStatusMessages

설정하면 호스팅 시작 상태 메시지가 표시되지 않습니다.

키: suppressStatusMessages
형식: bool(true/1 또는 false/0)
기본값: false
환경 변수: {PREFIX_}SUPPRESSSTATUSMESSAGES

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

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

URL

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

키: urls
형식: string
기본값: http://localhost:5000 및 https://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* 차이점은 메서드가 반환되기 전에 호스트가 완료되기를 기다리는 반면 메서드는 Start* 즉시 반환된다는 Run* Start* 것입니다. 메서드는 Run* 일반적으로 콘솔 앱에서 사용되는 반면 Start* 메서드는 일반적으로 장기 실행 서비스에서 사용됩니다.

Run

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

RunAsync

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

RunConsoleAsync

RunConsoleAsync는 콘솔을 지원하고, 호스트를 빌드 및 시작하고, 종료를 위해 Ctrl+C/SIGINT(Windows), ⌘+C(macOS) 또는 SIGTERM을 수신 대기합니다.

Start

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

StartAsync

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

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

StopAsync

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

WaitForShutdown

WaitForShutdown는 IHostLifetime에 의해 종료가 트리거될 때까지(예: Ctrl+C/SIGINT(Windows), ⌘+C(macOS) 또는 SIGTERM을 통해) 호출 스레드를 차단합니다.

WaitForShutdownAsync

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

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

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

호스트 정의

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

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

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

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

호스트 설정

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

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

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 메서드는 동일하지만 CreateHostBuilder는 ConfigureWebHostDefaults를 호출합니다.

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 환경에서 실행되는 경우.
    • 환경 변수입니다.
    • 명령줄 인수.
  • 다음 로깅 공급자를 추가합니다.
    • 콘솔
    • 디버그
    • 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:

  • Ctrl+C/SIGINT(Windows), ⌘+C(macOS) 또는 SIGTERM을 수신 대기하고 StopApplication을 트리거하여 종료 프로세스를 시작합니다.
  • RunAsync 및 WaitForShutdownAsync와 같은 확장의 차단을 해제합니다.

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_ 접두사가 포함될 수 있습니다. 이들은 다음 설정 목록에 {PREFIX_} 자리 표시자로 표시되어 있습니다. 자세한 내용은 기본 작성기 설정 섹션 및 구성: 환경 변수를 참조하세요.

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, Staging 및 Production을 포함합니다. 값은 대/소문자를 구분하지 않습니다.

키: environment
형식: string
기본값: Production
환경 변수: {PREFIX_}ENVIRONMENT

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

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

ShutdownTimeout

HostOptions.ShutdownTimeout은 StopAsync에 대한 시간 제한을 설정합니다. 기본값은 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.json 및 appsettings.{Environment}.json은 파일이 변경될 때 다시 로드됩니다. ASP.NET Core 5.0 이상에서 해당 다시 로드 동작을 사용하지 않도록 설정하려면 hostBuilder:reloadConfigOnChange 키를 false로 설정합니다.

키: hostBuilder:reloadConfigOnChange
형식: bool(true 또는 false)
기본값: true
명령줄 인수: hostBuilder:reloadConfigOnChange
환경 변수: {PREFIX_}hostBuilder:reloadConfigOnChange

Warning

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

웹앱 설정

일부 호스트 설정은 HTTP 워크로드에만 적용됩니다. 기본적으로 이러한 설정을 구성하는 데 사용되는 환경 변수에는 DOTNET_ 또는 ASPNETCORE_ 접두사가 포함될 수 있습니다. 이들은 다음 설정 목록에 {PREFIX_} 자리 표시자로 표시되어 있습니다.

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

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

CaptureStartupErrors

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

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

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

키: detailedErrors
형식: bool(true/1 또는 false/0)
기본값: 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 또는 false/0)
기본값: false
환경 변수: {PREFIX_}PREFERHOSTINGURLS

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

키: preventHostingStartup
형식: bool(true/1 또는 false/0)
기본값: 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>();

SuppressStatusMessages

설정하면 호스팅 시작 상태 메시지가 표시되지 않습니다.

키: suppressStatusMessages
형식: bool(true/1 또는 false/0)
기본값: false
환경 변수: {PREFIX_}SUPPRESSSTATUSMESSAGES

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

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

URL

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

키: urls
형식: string
기본값: http://localhost:5000 및 https://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* 차이점은 메서드가 반환되기 전에 호스트가 완료되기를 기다리는 반면 메서드는 Start* 즉시 반환된다는 Run* Start* 것입니다. 메서드는 Run* 일반적으로 콘솔 앱에서 사용되는 반면 Start* 메서드는 일반적으로 장기 실행 서비스에서 사용됩니다.

Run

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

RunAsync

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

RunConsoleAsync

RunConsoleAsync는 콘솔을 지원하고, 호스트를 빌드 및 시작하고, 종료를 위해 Ctrl+C/SIGINT(Windows), ⌘+C(macOS) 또는 SIGTERM을 수신 대기합니다.

Start

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

StartAsync

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

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

StopAsync

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

WaitForShutdown

WaitForShutdown는 IHostLifetime에 의해 종료가 트리거될 때까지(예: Ctrl+C/SIGINT(Windows), ⌘+C(macOS) 또는 SIGTERM을 통해) 호출 스레드를 차단합니다.

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(종속성 주입)
  • 로깅
  • 구성
  • IHostedService 구현

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

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

호스트 설정

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

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

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 메서드는 동일하지만 CreateHostBuilder는 ConfigureWebHostDefaults를 호출합니다.

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 환경에서 실행되는 경우.
    • 환경 변수입니다.
    • 명령줄 인수.
  • 다음 로깅 공급자를 추가합니다.
    • 콘솔
    • 디버그
    • 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:

  • Ctrl+C/SIGINT(Windows), ⌘+C(macOS) 또는 SIGTERM을 수신 대기하고 StopApplication을 트리거하여 종료 프로세스를 시작합니다.
  • RunAsync 및 WaitForShutdownAsync와 같은 확장의 차단을 해제합니다.

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_ 접두사가 포함될 수 있습니다. 이들은 다음 구성에서 {PREFIX_} 자리 표시자로 표시되어 있습니다.

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, Staging 및 Production을 포함합니다. 값은 대/소문자를 구분하지 않습니다.

키: environment
형식: string
기본값: Production
환경 변수: {PREFIX_}ENVIRONMENT

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

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

ShutdownTimeout

HostOptions.ShutdownTimeout은 StopAsync에 대한 시간 제한을 설정합니다. 기본값은 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의 확장 메서드를 사용할 수 있습니다. 확장 메서드를 호출하는 방법을 보여주는 코드 샘플은 다음 예제와 같이 webBuilder가 IWebHostBuilder의 인스턴스라고 가정합니다.

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

CaptureStartupErrors

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

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

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

webBuilder.CaptureStartupErrors(true);

DetailedErrors

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

키: detailedErrors
형식: bool(true/1 또는 false/0)
기본값: 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 또는 false/0)
기본값: false
환경 변수: {PREFIX_}PREFERHOSTINGURLS

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

webBuilder.PreferHostingUrls(true);

PreventHostingStartup

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

키: preventHostingStartup
형식: bool(true/1 또는 false/0)
기본값: 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>();

SuppressStatusMessages

설정하면 호스팅 시작 상태 메시지가 표시되지 않습니다.

키: suppressStatusMessages
형식: bool(true/1 또는 false/0)
기본값: false
환경 변수: {PREFIX_}SUPPRESSSTATUSMESSAGES

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

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

URL

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

키: urls
형식: string
기본값: http://localhost:5000 및 https://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* 차이점은 메서드가 반환되기 전에 호스트가 완료되기를 기다리는 반면 메서드는 Start* 즉시 반환된다는 Run* Start* 것입니다. 메서드는 Run* 일반적으로 콘솔 앱에서 사용되는 반면 Start* 메서드는 일반적으로 장기 실행 서비스에서 사용됩니다.

Run

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

RunAsync

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

RunConsoleAsync

RunConsoleAsync는 콘솔을 지원하고, 호스트를 빌드 및 시작하고, 종료를 위해 Ctrl+C/SIGINT(Windows), ⌘+C(macOS) 또는 SIGTERM을 수신 대기합니다.

Start

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

StartAsync

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

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

StopAsync

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

WaitForShutdown

WaitForShutdown는 IHostLifetime에 의해 종료가 트리거될 때까지(예: Ctrl+C/SIGINT(Windows), ⌘+C(macOS) 또는 SIGTERM을 통해) 호출 스레드를 차단합니다.

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

추가 리소스