ASP.NET Core 웹 호스트

ASP.NET Core 앱은 호스트를 구성 및 실행합니다. 호스트는 앱 시작 및 수명 관리를 담당합니다. 최소한으로 호스트는 서버 및 요청 처리 파이프라인을 구성합니다. 호스트는 로깅, 종속성 주입 및 구성을 설정할 수도 있습니다.

이 문서에서는 이전 버전과의 호환성을 위해서만 사용 가능한 상태를 유지하는 웹 호스트에 설명합니다. ASP.NET Core 템플릿은 웹앱에 권장되는 WebApplicationBuilderWebApplication을 만듭니다. WebApplicationBuilderWebApplication에 대한 자세한 내용은 ASP.NET Core 5.0에서 6.0으로 마이그레이션을 참조하세요.

호스트 설정

의 인스턴스를 사용하여 호스트를 만듭니다 IWebHostBuilder. 일반적으로 앱의 진입점인 Program.csMain 메서드에서 수행됩니다. 일반적인 앱은 호스트 설정을 시작하기 위해 호출 CreateDefaultBuilder 합니다.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

CreateDefaultBuilder를 호출하는 코드는 CreateWebHostBuilder라는 메서드에 포함되어, 빌더 개체에서 Run을 호출하는 Main의 코드와 분리됩니다. 이 분리는 Entity Framework Core 도구를 사용하는 경우 필요합니다. 이 도구는 앱을 실행하지 않고 호스트를 구성하기 위해 디자인 타임에 호출할 수 있는 CreateWebHostBuilder 메서드를 찾으려 합니다. IDesignTimeDbContextFactory를 구현하는 방법도 있습니다. 자세한 내용은 디자인 타임 DbContext 만들기를 참조하세요.

CreateDefaultBuilder은 다음 작업을 수행합니다.

CreateDefaultBuilder에 의해 정의된 구성은 ConfigureAppConfiguration, ConfigureLogging, 기타 메서드 및 IWebHostBuilder의 확장 메서드로 재정의되고 확대될 수 있습니다. 몇 가지 예제는 다음과 같습니다.

  • ConfigureAppConfiguration은 앱에 대한 추가 IConfiguration을 지정하는 데 사용됩니다. 다음 ConfigureAppConfiguration 호출은 appsettings.xml 파일에 앱 구성을 포함하는 대리자를 추가합니다. ConfigureAppConfiguration이 여러 번 호출될 수 있습니다. 이 구성은 호스트(예: 서버 URL 또는 환경)에 적용되지 않습니다. 호스트 구성 값 섹션을 참조하세요.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • 다음 ConfigureLogging 호출은 최소 로깅 수준(SetMinimumLevel)을 LogLevel.Warning으로 구성하는 대리자를 추가합니다. 이 설정은 () 및 (LogLevel.Debug)에서 appsettings.Development.json 구성된 설정을 재정의합니다CreateDefaultBuilder.LogLevel.Errorappsettings.Production.json ConfigureLogging이 여러 번 호출될 수 있습니다.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • ConfigureKestrel에 대한 다음 호출은 Kestrel이 CreateDefaultBuilder에 의해 구성될 때 설정된 30,000,000바이트의 기본 Limits.MaxRequestBodySize를 재정의합니다.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

콘텐츠 루트는 호스트가 MVC 뷰 파일과 같은 콘텐츠 파일을 검색하는 위치를 결정합니다. 앱이 프로젝트의 루트 폴더에서 시작되면 프로젝트의 루트 폴더가 콘텐츠 루트로 사용됩니다. 이것이 Visual Studiodotnet 새 템플릿에서 사용되는 기본값입니다.

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

참고 항목

ASP.NET Core 2.x에서는 정적 CreateDefaultBuilder 메서드 사용에 대한 대안으로 WebHostBuilder에서 호스트를 만들 수 있도록 지원합니다.

호스트 ConfigureConfigureServices 를 설정할 때 메서드를 제공할 수 있습니다. Startup 클래스가 지정된 경우 Configure 메서드를 정의해야 합니다. 자세한 내용은 ASP.NET Core에서 앱 시작을 참조하세요. ConfigureServices에 대한 여러 호출은 서로 추가합니다. WebHostBuilder에서 Configure 또는 UseStartup에 대한 여러 호출은 이전 설정을 대체합니다.

호스트 구성 값

WebHostBuilder 에서는 다음 방법을 사용하여 호스트 구성 값을 설정합니다.

  • ASPNETCORE_{configurationKey} 형식의 환경 변수를 포함하는 호스트 빌더 구성. 예: ASPNETCORE_ENVIRONMENT.
  • UseContentRootUseConfiguration와 같은 확장(구성 재정의 섹션 참조).
  • UseSetting 및 연결된 키. UseSetting을 사용하여 값을 설정할 때 값은 형식에 관계 없이 문자열로 설정됩니다.

호스트는 마지막에 값을 설정한 옵션을 사용합니다. 자세한 내용은 다음 섹션의 구성 재정의를 참조하세요.

애플리케이션 키(이름)

호스트 생성 중에 UseStartup 또는 Configure가 호출되는 경우 IWebHostEnvironment.ApplicationName 속성이 자동으로 설정됩니다. 해당 값은 앱의 진입점을 포함하는 어셈블리의 이름으로 설정됩니다. 값을 명시적으로 설정하려면 다음을 WebHostDefaults.ApplicationKey사용합니다.

: applicationName
형식: string
기본값: 앱의 진입점을 포함하는 어셈블리의 이름입니다.
설정 방법: UseSetting
환경 변수: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

시작 오류 캡처

이 설정은 시작 오류의 캡처를 제어합니다.

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

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

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

콘텐츠 루트

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

: contentRoot
형식: string
기본값: 앱 어셈블리가 있는 폴더가 기본값으로 지정됩니다.
설정 방법: UseContentRoot
환경 변수: ASPNETCORE_CONTENTROOT

콘텐츠 루트는 또한 웹 루트에 대한 기본 경로로 사용됩니다. 콘텐츠 루트 경로가 존재하지 않는 경우 호스트가 시작되지 않습니다.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

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

자세한 오류

자세한 오류를 캡처해야 하는지를 결정합니다.

: detailedErrors
형식: bool(true 또는 1)
기본값: false
설정 방법: UseSetting
환경 변수: ASPNETCORE_DETAILEDERRORS

사용하는 경우(또는 환경Development로 설정된 경우) 앱은 자세한 예외를 캡처합니다.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

Environment

앱의 환경을 설정합니다.

: environment
형식: string
기본값: Production
설정 방법: UseEnvironment
환경 변수: ASPNETCORE_ENVIRONMENT

환경은 어떠한 값으로도 설정할 수 있습니다. 프레임워크에서 정의된 값은 Development, StagingProduction을 포함합니다. 값은 대/소문자를 구분하지 않습니다. 기본적으로 환경ASPNETCORE_ENVIRONMENT 환경 변수에서 읽습니다. Visual Studio를 사용하는 경우 파일에서 환경 변수를 launchSettings.json 설정할 수 있습니다. 자세한 내용은 ASP.NET Core에서 여러 환경 사용을 참조하세요.

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

호스팅 시작 어셈블리

앱의 호스팅 시작 어셈블리를 설정합니다.

: hostingStartupAssemblies
형식: string
기본값: 빈 문자열
설정 방법: UseSetting
환경 변수: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

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

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

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

HTTPS 포트

HTTPS 리디렉션 포트를 설정합니다. HTTPS 적용에 사용됩니다.

: https_port
형식: string
기본값: 기본값이 설정되지 않았습니다.
설정 방법: UseSetting
환경 변수: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

호스팅 시작 제외 어셈블리

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

: hostingStartupExcludeAssemblies
형식: string
기본값: 빈 문자열
설정 방법: UseSetting
환경 변수: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

호스팅 URL 선호

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

: preferHostingUrls
형식: bool(true 또는 1)
기본값: false
설정 방법: PreferHostingUrls
환경 변수: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

호스팅 시작 방지

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

: preventHostingStartup
형식: bool(true 또는 1)
기본값: false
설정 방법: UseSetting
환경 변수: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

서버 URL

서버에서 요청을 수신해야 하는 포트와 프로토콜이 있는 IP 주소 또는 호스트 주소를 나타냅니다.

: urls
형식: string
기본값:http://localhost:5000
설정 방법: UseUrls
환경 변수: ASPNETCORE_URLS

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

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

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

시스템 종료 제한 시간

웹 호스트가 종료될 때까지 기다리는 시간을 지정합니다.

: shutdownTimeoutSeconds
형식: int
기본값: 5
설정 방법: UseShutdownTimeout
환경 변수: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

키가 UseSetting을 통해 int를 허용하더라도(예: .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")) UseShutdownTimeout 확장 메서드는 TimeSpan을 사용합니다.

제한 시간 기간 동안 호스팅은:

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

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

시작 어셈블리

Startup 클래스를 검색할 어셈블리를 결정합니다.

: startupAssembly
형식: string
기본값: 앱의 어셈블리
설정 방법: UseStartup
환경 변수: ASPNETCORE_STARTUPASSEMBLY

이름(string) 또는 형식(TStartup)으로 어셈블리를 참조할 수 있습니다. UseStartup 메서드가 여러 개 호출된 경우 마지막 메서드가 우선 적용됩니다.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

웹 루트

앱의 정적 자산에 대한 상대 경로를 설정합니다.

: webroot
형식: string
기본값: 기본값은 wwwroot입니다. {content root}/wwwroot 경로가 존재해야 합니다. 경로가 존재하지 않으면 no-op 파일 공급자가 사용됩니다.
설정 방법: UseWebRoot
환경 변수: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

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

구성 재정의

구성을 사용하여 웹 호스트를 구성합니다. 다음 예제에서 호스트 구성은 필요에 따라 파일에 지정됩니다 hostsettings.json . 파일에서 로드된 모든 구성은 hostsettings.json 명령줄 인수에 의해 재정의될 수 있습니다. 기본 제공된 구성(config에 있음)은 UseConfiguration을 통해 호스트를 구성하는 데 사용됩니다. IWebHostBuilder 구성이 앱의 구성에 추가되지만 반대의 경우에는 그렇지 않습니다. ConfigureAppConfigurationIWebHostBuilder 구성에 영향을 주지 않습니다.

구성에서 제공하는 UseUrlshostsettings.json 구성을 먼저 재정의하고, 명령줄 인수 구성을 두 번째로 재정의합니다.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:

{
    urls: "http://*:5005"
}

참고 항목

UseConfiguration은 제공된 IConfiguration의 키만 호스트 빌더 구성으로 복사합니다. 따라서 JSON, INI 및 XML 설정 파일에 대해 reloadOnChange: true를 설정해도 영향을 미치지 않습니다.

특정 URL에서 실행하는 호스트를 지정하려면 dotnet run 실행 시 원하는 값을 명령 프롬프트에서 전달할 수 있습니다. 명령줄 인수는 파일의 값을 재정의 urlshostsettings.json 하고 서버는 포트 8080에서 수신 대기합니다.

dotnet run --urls "http://*:8080"

호스트 관리

Run

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

host.Run();

Start

해당 Start 메서드를 호출하여 비차단 방식으로 호스트를 실행합니다.

using (host)
{
    host.Start();
    Console.ReadLine();
}

URL 목록이 Start 메서드에 전달되면 지정된 URL에서 수신합니다.

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

앱은 정적 편의 메서드를 사용하여 CreateDefaultBuilder의 미리 구성된 기본 값을 사용하는 새 호스트를 초기화하고 시작합니다. 이러한 메서드는 콘솔 출력 WaitForShutdown 없이 서버를 시작하고 중단을 기다립니다(Ctrl-C/SIGINT 또는 SIGTERM).

Start(RequestDelegate app)

RequestDelegate로 시작합니다.

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

중단(Ctrl-C/SIGINT 또는 SIGTERM)이 발생할 때까지 브라우저에서 http://localhost:5000이 응답 "Hello World!" WaitForShutdown 블록을 수신하도록 요청합니다. 앱은 Console.WriteLine 메시지를 표시하고 종료하기 위한 키 입력을 대기합니다.

Start(string url, RequestDelegate app)

URL 및 RequestDelegate로 시작합니다.

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

앱이 http://localhost:8080에서 응답한다는 점을 제외하고 Start(RequestDelegate app)와 동일한 결과가 생성됩니다.

Start(Action<IRouteBuilder> routeBuilder)

IRouteBuilder의 인스턴스(Microsoft.AspNetCore.Routing)를 사용하여 라우팅 미들웨어를 사용합니다.

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

예제에서는 다음 브라우저 요청을 사용합니다.

Request Response
http://localhost:5000/hello/Martin Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! “ooops!” 문자열을 사용하여 예외를 throw합니다.
http://localhost:5000/throw “Uh oh!” 문자열을 사용하여 예외를 throw합니다.
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Hello World!

WaitForShutdown은 중단(Ctrl-C/SIGINT 또는 SIGTERM)이 발생할 때까지 차단합니다. 앱은 Console.WriteLine 메시지를 표시하고 종료하기 위한 키 입력을 대기합니다.

Start(string url, Action<IRouteBuilder> routeBuilder)

URL 및 IRouteBuilder의 인스턴스를 사용합니다.

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

앱이 http://localhost:8080에서 응답한다는 점을 제외하고 Start(Action<IRouteBuilder> routeBuilder)와 동일한 결과가 생성됩니다.

StartWith(Action<IApplicationBuilder> app)

대리자를 제공하여 IApplicationBuilder를 구성합니다.

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

중단(Ctrl-C/SIGINT 또는 SIGTERM)이 발생할 때까지 브라우저에서 http://localhost:5000이 응답 "Hello World!" WaitForShutdown 블록을 수신하도록 요청합니다. 앱은 Console.WriteLine 메시지를 표시하고 종료하기 위한 키 입력을 대기합니다.

StartWith(string url, Action<IApplicationBuilder> app)

URL 및 대리자를 제공하여 IApplicationBuilder를 구성합니다.

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

앱이 http://localhost:8080에서 응답한다는 점을 제외하고 StartWith(Action<IApplicationBuilder> app)와 동일한 결과가 생성됩니다.

IWebHostEnvironment 인터페이스

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

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

규칙 기반 접근 방식은 시작할 때 환경에 따라 앱을 구성하는 데 사용할 수 있습니다. 또는 ConfigureServices에서 사용할 수 있도록 IWebHostEnvironmentStartup 생성자에 주입합니다.

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

참고 항목

IsDevelopment 확장 메서드 외에 IWebHostEnvironmentIsStaging, IsProductionIsEnvironment(string environmentName) 메서드를 제공합니다. 자세한 내용은 ASP.NET Core에서 여러 환경 사용을 참조하세요.

또한 IWebHostEnvironment 서비스를 파이프라인 처리를 설정하기 위한 Configure 메서드에 직접 주입할 수 있습니다.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

사용자 지정 미들웨어를 만들 때 IWebHostEnvironmentInvoke 메서드에 주입할 수 있습니다.

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

IHostApplicationLifetime 인터페이스

IHostApplicationLifetime은 시작 후 및 종료 작업을 허용합니다. 인터페이스에서 세 가지 속성은 취소 토큰으로, 시작 및 종료 이벤트를 정의하는 Action 메서드를 등록하는 데 사용됩니다.

취소 토큰 트리거되는 경우…
ApplicationStarted 호스트가 완벽하게 시작되었습니다.
ApplicationStopped 호스트가 정상적으로 종료되었습니다. 모든 요청이 처리되어야 합니다. 종료는 이 이벤트가 완료될 때까지 차단합니다.
ApplicationStopping 호스트가 정상적으로 종료되고 있습니다. 요청은 계속 처리할 수 있습니다. 종료는 이 이벤트가 완료될 때까지 차단합니다.
public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

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

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

범위 유효성 검사

앱의 환경이 개발인 경우 CreateDefaultBuilderServiceProviderOptions.ValidateScopestrue로 설정합니다.

ValidateScopestrue로 설정된 경우 기본 서비스 공급자는 다음을 확인하기 위해 검사를 수행합니다.

  • 범위가 지정된 서비스는 직접 또는 간접적으로 루트 서비스 공급자에서 해결되지 않습니다.
  • 범위가 지정된 서비스는 직접 또는 간접적으로 싱글톤에 삽입되지 않습니다.

루트 서비스 공급자는 BuildServiceProvider를 호출할 때 만들어집니다. 루트 서비스 공급자의 수명은 공급자가 앱과 함께 시작되고 앱이 종료될 때 삭제되는 앱/서버의 수명에 해당합니다.

범위가 지정된 서비스는 서비스를 만든 컨테이너에 의해 삭제됩니다. 범위가 지정된 서비스가 루트 컨테이너에서 만들어지는 경우 서비스의 수명은 사실상 싱글톤으로 승격됩니다. 해당 서비스는 앱/서버가 종료될 때 루트 컨테이너에 의해서만 삭제되기 때문입니다. 서비스 범위의 유효성 검사는 BuildServiceProvider가 호출될 경우 이러한 상황을 감지합니다.

프로덕션 환경을 포함하여 범위의 유효성을 항상 검사하려면 호스트 작성기에서 with UseDefaultServiceProvider 를 구성 ServiceProviderOptions 합니다.

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

추가 리소스

ASP.NET Core 앱은 호스트를 구성 및 실행합니다. 호스트는 앱 시작 및 수명 관리를 담당합니다. 최소한으로 호스트는 서버 및 요청 처리 파이프라인을 구성합니다. 호스트는 로깅, 종속성 주입 및 구성을 설정할 수도 있습니다.

이 문서에서는 이전 버전과의 호환성을 위해서만 사용 가능한 상태를 유지하는 웹 호스트에 설명합니다. ASP.NET Core 템플릿은 모든 앱 형식에 대해 권장되는 .NET 제네릭 호스트를 만듭니다.

호스트 설정

의 인스턴스를 사용하여 호스트를 만듭니다 IWebHostBuilder. 이는 일반적으로 앱의 진입점에서 수행되는 Main 메서드입니다.

프로젝트 템플릿의 Main 위치는 .에 있습니다 Program.cs. 일반적인 앱은 호스트 설정을 시작하기 위해 호출 CreateDefaultBuilder 합니다.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

CreateDefaultBuilder를 호출하는 코드는 CreateWebHostBuilder라는 메서드에 포함되어, 빌더 개체에서 Run을 호출하는 Main의 코드와 분리됩니다. 이 분리는 Entity Framework Core 도구를 사용하는 경우 필요합니다. 이 도구는 앱을 실행하지 않고 호스트를 구성하기 위해 디자인 타임에 호출할 수 있는 CreateWebHostBuilder 메서드를 찾으려 합니다. IDesignTimeDbContextFactory를 구현하는 방법도 있습니다. 자세한 내용은 디자인 타임 DbContext 만들기를 참조하세요.

CreateDefaultBuilder은 다음 작업을 수행합니다.

CreateDefaultBuilder에 의해 정의된 구성은 ConfigureAppConfiguration, ConfigureLogging, 기타 메서드 및 IWebHostBuilder의 확장 메서드로 재정의되고 확대될 수 있습니다. 몇 가지 예제는 다음과 같습니다.

  • ConfigureAppConfiguration은 앱에 대한 추가 IConfiguration을 지정하는 데 사용됩니다. 다음 ConfigureAppConfiguration 호출은 appsettings.xml 파일에 앱 구성을 포함하는 대리자를 추가합니다. ConfigureAppConfiguration이 여러 번 호출될 수 있습니다. 이 구성은 호스트(예: 서버 URL 또는 환경)에 적용되지 않습니다. 호스트 구성 값 섹션을 참조하세요.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • 다음 ConfigureLogging 호출은 최소 로깅 수준(SetMinimumLevel)을 LogLevel.Warning으로 구성하는 대리자를 추가합니다. 이 설정은 () 및 (LogLevel.Debug)에서 appsettings.Development.json 구성된 설정을 재정의합니다CreateDefaultBuilder.LogLevel.Errorappsettings.Production.json ConfigureLogging이 여러 번 호출될 수 있습니다.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • ConfigureKestrel에 대한 다음 호출은 Kestrel이 CreateDefaultBuilder에 의해 구성될 때 설정된 30,000,000바이트의 기본 Limits.MaxRequestBodySize를 재정의합니다.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

콘텐츠 루트는 호스트가 MVC 뷰 파일과 같은 콘텐츠 파일을 검색하는 위치를 결정합니다. 앱이 프로젝트의 루트 폴더에서 시작되면 프로젝트의 루트 폴더가 콘텐츠 루트로 사용됩니다. 이것이 Visual Studiodotnet 새 템플릿에서 사용되는 기본값입니다.

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

참고 항목

ASP.NET Core 2.x에서는 정적 CreateDefaultBuilder 메서드 사용에 대한 대안으로 WebHostBuilder에서 호스트를 만들 수 있도록 지원합니다.

호스트 ConfigureConfigureServices 를 설정할 때 메서드를 제공할 수 있습니다. Startup 클래스가 지정된 경우 Configure 메서드를 정의해야 합니다. 자세한 내용은 ASP.NET Core에서 앱 시작을 참조하세요. ConfigureServices에 대한 여러 호출은 서로 추가합니다. WebHostBuilder에서 Configure 또는 UseStartup에 대한 여러 호출은 이전 설정을 대체합니다.

호스트 구성 값

WebHostBuilder 에서는 다음 방법을 사용하여 호스트 구성 값을 설정합니다.

  • ASPNETCORE_{configurationKey} 형식의 환경 변수를 포함하는 호스트 빌더 구성. 예: ASPNETCORE_ENVIRONMENT.
  • UseContentRootUseConfiguration와 같은 확장(구성 재정의 섹션 참조).
  • UseSetting 및 연결된 키. UseSetting을 사용하여 값을 설정할 때 값은 형식에 관계 없이 문자열로 설정됩니다.

호스트는 마지막에 값을 설정한 옵션을 사용합니다. 자세한 내용은 다음 섹션의 구성 재정의를 참조하세요.

애플리케이션 키(이름)

호스트 생성 중에 UseStartup 또는 Configure가 호출되는 경우 IWebHostEnvironment.ApplicationName 속성이 자동으로 설정됩니다. 해당 값은 앱의 진입점을 포함하는 어셈블리의 이름으로 설정됩니다. 값을 명시적으로 설정하려면 다음을 WebHostDefaults.ApplicationKey사용합니다.

: applicationName
형식: string
기본값: 앱의 진입점을 포함하는 어셈블리의 이름입니다.
설정 방법: UseSetting
환경 변수: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

시작 오류 캡처

이 설정은 시작 오류의 캡처를 제어합니다.

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

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

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

콘텐츠 루트

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

: contentRoot
형식: string
기본값: 앱 어셈블리가 있는 폴더가 기본값으로 지정됩니다.
설정 방법: UseContentRoot
환경 변수: ASPNETCORE_CONTENTROOT

콘텐츠 루트는 또한 웹 루트에 대한 기본 경로로 사용됩니다. 콘텐츠 루트 경로가 존재하지 않는 경우 호스트가 시작되지 않습니다.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

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

자세한 오류

자세한 오류를 캡처해야 하는지를 결정합니다.

: detailedErrors
형식: bool(true 또는 1)
기본값: false
설정 방법: UseSetting
환경 변수: ASPNETCORE_DETAILEDERRORS

사용하는 경우(또는 환경Development로 설정된 경우) 앱은 자세한 예외를 캡처합니다.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

Environment

앱의 환경을 설정합니다.

: environment
형식: string
기본값: Production
설정 방법: UseEnvironment
환경 변수: ASPNETCORE_ENVIRONMENT

환경은 어떠한 값으로도 설정할 수 있습니다. 프레임워크에서 정의된 값은 Development, StagingProduction을 포함합니다. 값은 대/소문자를 구분하지 않습니다. 기본적으로 환경ASPNETCORE_ENVIRONMENT 환경 변수에서 읽습니다. Visual Studio를 사용하는 경우 파일에서 환경 변수를 launchSettings.json 설정할 수 있습니다. 자세한 내용은 ASP.NET Core에서 여러 환경 사용을 참조하세요.

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

호스팅 시작 어셈블리

앱의 호스팅 시작 어셈블리를 설정합니다.

: hostingStartupAssemblies
형식: string
기본값: 빈 문자열
설정 방법: UseSetting
환경 변수: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

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

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

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

HTTPS 포트

HTTPS 리디렉션 포트를 설정합니다. HTTPS 적용에 사용됩니다.

: https_port
형식: string
기본값: 기본값이 설정되지 않았습니다.
설정 방법: UseSetting
환경 변수: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

호스팅 시작 제외 어셈블리

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

: hostingStartupExcludeAssemblies
형식: string
기본값: 빈 문자열
설정 방법: UseSetting
환경 변수: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

호스팅 URL 선호

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

: preferHostingUrls
형식: bool(true 또는 1)
기본값: false
설정 방법: PreferHostingUrls
환경 변수: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

호스팅 시작 방지

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

: preventHostingStartup
형식: bool(true 또는 1)
기본값: false
설정 방법: UseSetting
환경 변수: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

서버 URL

서버에서 요청을 수신해야 하는 포트와 프로토콜이 있는 IP 주소 또는 호스트 주소를 나타냅니다.

: urls
형식: string
기본값:http://localhost:5000
설정 방법: UseUrls
환경 변수: ASPNETCORE_URLS

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

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

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

시스템 종료 제한 시간

웹 호스트가 종료될 때까지 기다리는 시간을 지정합니다.

: shutdownTimeoutSeconds
형식: int
기본값: 5
설정 방법: UseShutdownTimeout
환경 변수: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

키가 UseSetting을 통해 int를 허용하더라도(예: .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")) UseShutdownTimeout 확장 메서드는 TimeSpan을 사용합니다.

제한 시간 기간 동안 호스팅은:

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

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

시작 어셈블리

Startup 클래스를 검색할 어셈블리를 결정합니다.

: startupAssembly
형식: string
기본값: 앱의 어셈블리
설정 방법: UseStartup
환경 변수: ASPNETCORE_STARTUPASSEMBLY

이름(string) 또는 형식(TStartup)으로 어셈블리를 참조할 수 있습니다. UseStartup 메서드가 여러 개 호출된 경우 마지막 메서드가 우선 적용됩니다.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

웹 루트

앱의 정적 자산에 대한 상대 경로를 설정합니다.

: webroot
형식: string
기본값: 기본값은 wwwroot입니다. {content root}/wwwroot 경로가 존재해야 합니다. 경로가 존재하지 않으면 no-op 파일 공급자가 사용됩니다.
설정 방법: UseWebRoot
환경 변수: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

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

구성 재정의

구성을 사용하여 웹 호스트를 구성합니다. 다음 예제에서 호스트 구성은 필요에 따라 파일에 지정됩니다 hostsettings.json . 파일에서 로드된 모든 구성은 hostsettings.json 명령줄 인수에 의해 재정의될 수 있습니다. 기본 제공된 구성(config에 있음)은 UseConfiguration을 통해 호스트를 구성하는 데 사용됩니다. IWebHostBuilder 구성이 앱의 구성에 추가되지만 반대의 경우에는 그렇지 않습니다. ConfigureAppConfigurationIWebHostBuilder 구성에 영향을 주지 않습니다.

구성에서 제공하는 UseUrlshostsettings.json 구성을 먼저 재정의하고, 명령줄 인수 구성을 두 번째로 재정의합니다.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:

{
    urls: "http://*:5005"
}

참고 항목

UseConfiguration은 제공된 IConfiguration의 키만 호스트 빌더 구성으로 복사합니다. 따라서 JSON, INI 및 XML 설정 파일에 대해 reloadOnChange: true를 설정해도 영향을 미치지 않습니다.

특정 URL에서 실행하는 호스트를 지정하려면 dotnet run 실행 시 원하는 값을 명령 프롬프트에서 전달할 수 있습니다. 명령줄 인수는 파일의 값을 재정의 urlshostsettings.json 하고 서버는 포트 8080에서 수신 대기합니다.

dotnet run --urls "http://*:8080"

호스트 관리

Run

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

host.Run();

Start

해당 Start 메서드를 호출하여 비차단 방식으로 호스트를 실행합니다.

using (host)
{
    host.Start();
    Console.ReadLine();
}

URL 목록이 Start 메서드에 전달되면 지정된 URL에서 수신합니다.

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

앱은 정적 편의 메서드를 사용하여 CreateDefaultBuilder의 미리 구성된 기본 값을 사용하는 새 호스트를 초기화하고 시작합니다. 이러한 메서드는 콘솔 출력 WaitForShutdown 없이 서버를 시작하고 중단을 기다립니다(Ctrl-C/SIGINT 또는 SIGTERM).

Start(RequestDelegate app)

RequestDelegate로 시작합니다.

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

중단(Ctrl-C/SIGINT 또는 SIGTERM)이 발생할 때까지 브라우저에서 http://localhost:5000이 응답 "Hello World!" WaitForShutdown 블록을 수신하도록 요청합니다. 앱은 Console.WriteLine 메시지를 표시하고 종료하기 위한 키 입력을 대기합니다.

Start(string url, RequestDelegate app)

URL 및 RequestDelegate로 시작합니다.

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

앱이 http://localhost:8080에서 응답한다는 점을 제외하고 Start(RequestDelegate app)와 동일한 결과가 생성됩니다.

Start(Action<IRouteBuilder> routeBuilder)

IRouteBuilder의 인스턴스(Microsoft.AspNetCore.Routing)를 사용하여 라우팅 미들웨어를 사용합니다.

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

예제에서는 다음 브라우저 요청을 사용합니다.

Request Response
http://localhost:5000/hello/Martin Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! “ooops!” 문자열을 사용하여 예외를 throw합니다.
http://localhost:5000/throw “Uh oh!” 문자열을 사용하여 예외를 throw합니다.
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Hello World!

WaitForShutdown은 중단(Ctrl-C/SIGINT 또는 SIGTERM)이 발생할 때까지 차단합니다. 앱은 Console.WriteLine 메시지를 표시하고 종료하기 위한 키 입력을 대기합니다.

Start(string url, Action<IRouteBuilder> routeBuilder)

URL 및 IRouteBuilder의 인스턴스를 사용합니다.

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

앱이 http://localhost:8080에서 응답한다는 점을 제외하고 Start(Action<IRouteBuilder> routeBuilder)와 동일한 결과가 생성됩니다.

StartWith(Action<IApplicationBuilder> app)

대리자를 제공하여 IApplicationBuilder를 구성합니다.

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

중단(Ctrl-C/SIGINT 또는 SIGTERM)이 발생할 때까지 브라우저에서 http://localhost:5000이 응답 "Hello World!" WaitForShutdown 블록을 수신하도록 요청합니다. 앱은 Console.WriteLine 메시지를 표시하고 종료하기 위한 키 입력을 대기합니다.

StartWith(string url, Action<IApplicationBuilder> app)

URL 및 대리자를 제공하여 IApplicationBuilder를 구성합니다.

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

앱이 http://localhost:8080에서 응답한다는 점을 제외하고 StartWith(Action<IApplicationBuilder> app)와 동일한 결과가 생성됩니다.

IWebHostEnvironment 인터페이스

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

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

규칙 기반 접근 방식은 시작할 때 환경에 따라 앱을 구성하는 데 사용할 수 있습니다. 또는 ConfigureServices에서 사용할 수 있도록 IWebHostEnvironmentStartup 생성자에 주입합니다.

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

참고 항목

IsDevelopment 확장 메서드 외에 IWebHostEnvironmentIsStaging, IsProductionIsEnvironment(string environmentName) 메서드를 제공합니다. 자세한 내용은 ASP.NET Core에서 여러 환경 사용을 참조하세요.

또한 IWebHostEnvironment 서비스를 파이프라인 처리를 설정하기 위한 Configure 메서드에 직접 주입할 수 있습니다.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

사용자 지정 미들웨어를 만들 때 IWebHostEnvironmentInvoke 메서드에 주입할 수 있습니다.

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

IHostApplicationLifetime 인터페이스

IHostApplicationLifetime은 시작 후 및 종료 작업을 허용합니다. 인터페이스에서 세 가지 속성은 취소 토큰으로, 시작 및 종료 이벤트를 정의하는 Action 메서드를 등록하는 데 사용됩니다.

취소 토큰 트리거되는 경우…
ApplicationStarted 호스트가 완벽하게 시작되었습니다.
ApplicationStopped 호스트가 정상적으로 종료되었습니다. 모든 요청이 처리되어야 합니다. 종료는 이 이벤트가 완료될 때까지 차단합니다.
ApplicationStopping 호스트가 정상적으로 종료되고 있습니다. 요청은 계속 처리할 수 있습니다. 종료는 이 이벤트가 완료될 때까지 차단합니다.
public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

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

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

범위 유효성 검사

앱의 환경이 개발인 경우 CreateDefaultBuilderServiceProviderOptions.ValidateScopestrue로 설정합니다.

ValidateScopestrue로 설정된 경우 기본 서비스 공급자는 다음을 확인하기 위해 검사를 수행합니다.

  • 범위가 지정된 서비스는 직접 또는 간접적으로 루트 서비스 공급자에서 해결되지 않습니다.
  • 범위가 지정된 서비스는 직접 또는 간접적으로 싱글톤에 삽입되지 않습니다.

루트 서비스 공급자는 BuildServiceProvider를 호출할 때 만들어집니다. 루트 서비스 공급자의 수명은 공급자가 앱과 함께 시작되고 앱이 종료될 때 삭제되는 앱/서버의 수명에 해당합니다.

범위가 지정된 서비스는 서비스를 만든 컨테이너에 의해 삭제됩니다. 범위가 지정된 서비스가 루트 컨테이너에서 만들어지는 경우 서비스의 수명은 사실상 싱글톤으로 승격됩니다. 해당 서비스는 앱/서버가 종료될 때 루트 컨테이너에 의해서만 삭제되기 때문입니다. 서비스 범위의 유효성 검사는 BuildServiceProvider가 호출될 경우 이러한 상황을 감지합니다.

프로덕션 환경을 포함하여 범위의 유효성을 항상 검사하려면 호스트 작성기에서 with UseDefaultServiceProvider 를 구성 ServiceProviderOptions 합니다.

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

추가 리소스

ASP.NET Core 앱은 호스트를 구성 및 실행합니다. 호스트는 앱 시작 및 수명 관리를 담당합니다. 최소한으로 호스트는 서버 및 요청 처리 파이프라인을 구성합니다. 호스트는 로깅, 종속성 주입 및 구성을 설정할 수도 있습니다.

이 문서에서는 이전 버전과의 호환성을 위해서만 사용 가능한 상태를 유지하는 웹 호스트에 설명합니다. ASP.NET Core 템플릿은 모든 앱 형식에 대해 권장되는 .NET 제네릭 호스트를 만듭니다.

호스트 설정

의 인스턴스를 사용하여 호스트를 만듭니다 IWebHostBuilder. 이는 일반적으로 앱의 진입점에서 수행되는 Main 메서드입니다.

프로젝트 템플릿의 Main 위치는 .에 있습니다 Program.cs. 일반적인 앱은 호스트 설정을 시작하기 위해 호출 CreateDefaultBuilder 합니다.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

CreateDefaultBuilder를 호출하는 코드는 CreateWebHostBuilder라는 메서드에 포함되어, 빌더 개체에서 Run을 호출하는 Main의 코드와 분리됩니다. 이 분리는 Entity Framework Core 도구를 사용하는 경우 필요합니다. 이 도구는 앱을 실행하지 않고 호스트를 구성하기 위해 디자인 타임에 호출할 수 있는 CreateWebHostBuilder 메서드를 찾으려 합니다. IDesignTimeDbContextFactory를 구현하는 방법도 있습니다. 자세한 내용은 디자인 타임 DbContext 만들기를 참조하세요.

CreateDefaultBuilder은 다음 작업을 수행합니다.

CreateDefaultBuilder에 의해 정의된 구성은 ConfigureAppConfiguration, ConfigureLogging, 기타 메서드 및 IWebHostBuilder의 확장 메서드로 재정의되고 확대될 수 있습니다. 몇 가지 예제는 다음과 같습니다.

  • ConfigureAppConfiguration은 앱에 대한 추가 IConfiguration을 지정하는 데 사용됩니다. 다음 ConfigureAppConfiguration 호출은 appsettings.xml 파일에 앱 구성을 포함하는 대리자를 추가합니다. ConfigureAppConfiguration이 여러 번 호출될 수 있습니다. 이 구성은 호스트(예: 서버 URL 또는 환경)에 적용되지 않습니다. 호스트 구성 값 섹션을 참조하세요.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true);
        })
        ...
    
  • 다음 ConfigureLogging 호출은 최소 로깅 수준(SetMinimumLevel)을 LogLevel.Warning으로 구성하는 대리자를 추가합니다. 이 설정은 () 및 (LogLevel.Debug)에서 appsettings.Development.json 구성된 설정을 재정의합니다CreateDefaultBuilder.LogLevel.Errorappsettings.Production.json ConfigureLogging이 여러 번 호출될 수 있습니다.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => 
        {
            logging.SetMinimumLevel(LogLevel.Warning);
        })
        ...
    
  • ConfigureKestrel에 대한 다음 호출은 Kestrel이 CreateDefaultBuilder에 의해 구성될 때 설정된 30,000,000바이트의 기본 Limits.MaxRequestBodySize를 재정의합니다.

    WebHost.CreateDefaultBuilder(args)
        .ConfigureKestrel((context, options) =>
        {
            options.Limits.MaxRequestBodySize = 20000000;
        });
    

콘텐츠 루트는 호스트가 MVC 뷰 파일과 같은 콘텐츠 파일을 검색하는 위치를 결정합니다. 앱이 프로젝트의 루트 폴더에서 시작되면 프로젝트의 루트 폴더가 콘텐츠 루트로 사용됩니다. 이것이 Visual Studiodotnet 새 템플릿에서 사용되는 기본값입니다.

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

참고 항목

ASP.NET Core 2.x에서는 정적 CreateDefaultBuilder 메서드 사용에 대한 대안으로 WebHostBuilder에서 호스트를 만들 수 있도록 지원합니다.

호스트 ConfigureConfigureServices 를 설정할 때 메서드를 제공할 수 있습니다. Startup 클래스가 지정된 경우 Configure 메서드를 정의해야 합니다. 자세한 내용은 ASP.NET Core에서 앱 시작을 참조하세요. ConfigureServices에 대한 여러 호출은 서로 추가합니다. WebHostBuilder에서 Configure 또는 UseStartup에 대한 여러 호출은 이전 설정을 대체합니다.

호스트 구성 값

WebHostBuilder 에서는 다음 방법을 사용하여 호스트 구성 값을 설정합니다.

  • ASPNETCORE_{configurationKey} 형식의 환경 변수를 포함하는 호스트 빌더 구성. 예: ASPNETCORE_ENVIRONMENT.
  • UseContentRootUseConfiguration와 같은 확장(구성 재정의 섹션 참조).
  • UseSetting 및 연결된 키. UseSetting을 사용하여 값을 설정할 때 값은 형식에 관계 없이 문자열로 설정됩니다.

호스트는 마지막에 값을 설정한 옵션을 사용합니다. 자세한 내용은 다음 섹션의 구성 재정의를 참조하세요.

애플리케이션 키(이름)

호스트 생성 중에 UseStartup 또는 Configure가 호출되는 경우 IWebHostEnvironment.ApplicationName 속성이 자동으로 설정됩니다. 해당 값은 앱의 진입점을 포함하는 어셈블리의 이름으로 설정됩니다. 값을 명시적으로 설정하려면 다음을 WebHostDefaults.ApplicationKey사용합니다.

: applicationName
형식: string
기본값: 앱의 진입점을 포함하는 어셈블리의 이름입니다.
설정 방법: UseSetting
환경 변수: ASPNETCORE_APPLICATIONNAME

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.ApplicationKey, "CustomApplicationName")

시작 오류 캡처

이 설정은 시작 오류의 캡처를 제어합니다.

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

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

WebHost.CreateDefaultBuilder(args)
    .CaptureStartupErrors(true)

콘텐츠 루트

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

: contentRoot
형식: string
기본값: 앱 어셈블리가 있는 폴더가 기본값으로 지정됩니다.
설정 방법: UseContentRoot
환경 변수: ASPNETCORE_CONTENTROOT

콘텐츠 루트는 또한 웹 루트에 대한 기본 경로로 사용됩니다. 콘텐츠 루트 경로가 존재하지 않는 경우 호스트가 시작되지 않습니다.

WebHost.CreateDefaultBuilder(args)
    .UseContentRoot("c:\\<content-root>")

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

자세한 오류

자세한 오류를 캡처해야 하는지를 결정합니다.

: detailedErrors
형식: bool(true 또는 1)
기본값: false
설정 방법: UseSetting
환경 변수: ASPNETCORE_DETAILEDERRORS

사용하는 경우(또는 환경Development로 설정된 경우) 앱은 자세한 예외를 캡처합니다.

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.DetailedErrorsKey, "true")

Environment

앱의 환경을 설정합니다.

: environment
형식: string
기본값: Production
설정 방법: UseEnvironment
환경 변수: ASPNETCORE_ENVIRONMENT

환경은 어떠한 값으로도 설정할 수 있습니다. 프레임워크에서 정의된 값은 Development, StagingProduction을 포함합니다. 값은 대/소문자를 구분하지 않습니다. 기본적으로 환경ASPNETCORE_ENVIRONMENT 환경 변수에서 읽습니다. Visual Studio를 사용하는 경우 파일에서 환경 변수를 launchSettings.json 설정할 수 있습니다. 자세한 내용은 ASP.NET Core에서 여러 환경 사용을 참조하세요.

WebHost.CreateDefaultBuilder(args)
    .UseEnvironment(EnvironmentName.Development)

호스팅 시작 어셈블리

앱의 호스팅 시작 어셈블리를 설정합니다.

: hostingStartupAssemblies
형식: string
기본값: 빈 문자열
설정 방법: UseSetting
환경 변수: ASPNETCORE_HOSTINGSTARTUPASSEMBLIES

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

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

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupAssembliesKey, "assembly1;assembly2")

HTTPS 포트

HTTPS 리디렉션 포트를 설정합니다. HTTPS 적용에 사용됩니다.

: https_port
형식: string
기본값: 기본값이 설정되지 않았습니다.
설정 방법: UseSetting
환경 변수: ASPNETCORE_HTTPS_PORTS

WebHost.CreateDefaultBuilder(args)
    .UseSetting("https_port", "8080")

호스팅 시작 제외 어셈블리

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

: hostingStartupExcludeAssemblies
형식: string
기본값: 빈 문자열
설정 방법: UseSetting
환경 변수: ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.HostingStartupExcludeAssembliesKey, "assembly1;assembly2")

호스팅 URL 선호

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

: preferHostingUrls
형식: bool(true 또는 1)
기본값: false
설정 방법: PreferHostingUrls
환경 변수: ASPNETCORE_PREFERHOSTINGURLS

WebHost.CreateDefaultBuilder(args)
    .PreferHostingUrls(true)

호스팅 시작 방지

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

: preventHostingStartup
형식: bool(true 또는 1)
기본값: false
설정 방법: UseSetting
환경 변수: ASPNETCORE_PREVENTHOSTINGSTARTUP

WebHost.CreateDefaultBuilder(args)
    .UseSetting(WebHostDefaults.PreventHostingStartupKey, "true")

서버 URL

서버에서 요청을 수신해야 하는 포트와 프로토콜이 있는 IP 주소 또는 호스트 주소를 나타냅니다.

: urls
형식: string
기본값:http://localhost:5000
설정 방법: UseUrls
환경 변수: ASPNETCORE_URLS

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

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

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

시스템 종료 제한 시간

웹 호스트가 종료될 때까지 기다리는 시간을 지정합니다.

: shutdownTimeoutSeconds
형식: int
기본값: 5
설정 방법: UseShutdownTimeout
환경 변수: ASPNETCORE_SHUTDOWNTIMEOUTSECONDS

키가 UseSetting을 통해 int를 허용하더라도(예: .UseSetting(WebHostDefaults.ShutdownTimeoutKey, "10")) UseShutdownTimeout 확장 메서드는 TimeSpan을 사용합니다.

제한 시간 기간 동안 호스팅은:

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

WebHost.CreateDefaultBuilder(args)
    .UseShutdownTimeout(TimeSpan.FromSeconds(10))

시작 어셈블리

Startup 클래스를 검색할 어셈블리를 결정합니다.

: startupAssembly
형식: string
기본값: 앱의 어셈블리
설정 방법: UseStartup
환경 변수: ASPNETCORE_STARTUPASSEMBLY

이름(string) 또는 형식(TStartup)으로 어셈블리를 참조할 수 있습니다. UseStartup 메서드가 여러 개 호출된 경우 마지막 메서드가 우선 적용됩니다.

WebHost.CreateDefaultBuilder(args)
    .UseStartup("StartupAssemblyName")
WebHost.CreateDefaultBuilder(args)
    .UseStartup<TStartup>()

웹 루트

앱의 정적 자산에 대한 상대 경로를 설정합니다.

: webroot
형식: string
기본값: 기본값은 wwwroot입니다. {content root}/wwwroot 경로가 존재해야 합니다. 경로가 존재하지 않으면 no-op 파일 공급자가 사용됩니다.
설정 방법: UseWebRoot
환경 변수: ASPNETCORE_WEBROOT

WebHost.CreateDefaultBuilder(args)
    .UseWebRoot("public")

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

구성 재정의

구성을 사용하여 웹 호스트를 구성합니다. 다음 예제에서 호스트 구성은 필요에 따라 파일에 지정됩니다 hostsettings.json . 파일에서 로드된 모든 구성은 hostsettings.json 명령줄 인수에 의해 재정의될 수 있습니다. 기본 제공된 구성(config에 있음)은 UseConfiguration을 통해 호스트를 구성하는 데 사용됩니다. IWebHostBuilder 구성이 앱의 구성에 추가되지만 반대의 경우에는 그렇지 않습니다. ConfigureAppConfigurationIWebHostBuilder 구성에 영향을 주지 않습니다.

구성에서 제공하는 UseUrlshostsettings.json 구성을 먼저 재정의하고, 명령줄 인수 구성을 두 번째로 재정의합니다.

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

    public static IWebHostBuilder CreateWebHostBuilder(string[] args)
    {
        var config = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("hostsettings.json", optional: true)
            .AddCommandLine(args)
            .Build();

        return WebHost.CreateDefaultBuilder(args)
            .UseUrls("http://*:5000")
            .UseConfiguration(config)
            .Configure(app =>
            {
                app.Run(context => 
                    context.Response.WriteAsync("Hello, World!"));
            });
    }
}

hostsettings.json:

{
    urls: "http://*:5005"
}

참고 항목

UseConfiguration은 제공된 IConfiguration의 키만 호스트 빌더 구성으로 복사합니다. 따라서 JSON, INI 및 XML 설정 파일에 대해 reloadOnChange: true를 설정해도 영향을 미치지 않습니다.

특정 URL에서 실행하는 호스트를 지정하려면 dotnet run 실행 시 원하는 값을 명령 프롬프트에서 전달할 수 있습니다. 명령줄 인수는 파일의 값을 재정의 urlshostsettings.json 하고 서버는 포트 8080에서 수신 대기합니다.

dotnet run --urls "http://*:8080"

호스트 관리

Run

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

host.Run();

Start

해당 Start 메서드를 호출하여 비차단 방식으로 호스트를 실행합니다.

using (host)
{
    host.Start();
    Console.ReadLine();
}

URL 목록이 Start 메서드에 전달되면 지정된 URL에서 수신합니다.

var urls = new List<string>()
{
    "http://*:5000",
    "http://localhost:5001"
};

var host = new WebHostBuilder()
    .UseKestrel()
    .UseStartup<Startup>()
    .Start(urls.ToArray());

using (host)
{
    Console.ReadLine();
}

앱은 정적 편의 메서드를 사용하여 CreateDefaultBuilder의 미리 구성된 기본 값을 사용하는 새 호스트를 초기화하고 시작합니다. 이러한 메서드는 콘솔 출력 WaitForShutdown 없이 서버를 시작하고 중단을 기다립니다(Ctrl-C/SIGINT 또는 SIGTERM).

Start(RequestDelegate app)

RequestDelegate로 시작합니다.

using (var host = WebHost.Start(app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

중단(Ctrl-C/SIGINT 또는 SIGTERM)이 발생할 때까지 브라우저에서 http://localhost:5000이 응답 "Hello World!" WaitForShutdown 블록을 수신하도록 요청합니다. 앱은 Console.WriteLine 메시지를 표시하고 종료하기 위한 키 입력을 대기합니다.

Start(string url, RequestDelegate app)

URL 및 RequestDelegate로 시작합니다.

using (var host = WebHost.Start("http://localhost:8080", app => app.Response.WriteAsync("Hello, World!")))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

앱이 http://localhost:8080에서 응답한다는 점을 제외하고 Start(RequestDelegate app)와 동일한 결과가 생성됩니다.

Start(Action<IRouteBuilder> routeBuilder)

IRouteBuilder의 인스턴스(Microsoft.AspNetCore.Routing)를 사용하여 라우팅 미들웨어를 사용합니다.

using (var host = WebHost.Start(router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shutdown the host...");
    host.WaitForShutdown();
}

예제에서는 다음 브라우저 요청을 사용합니다.

Request Response
http://localhost:5000/hello/Martin Hello, Martin!
http://localhost:5000/buenosdias/Catrina Buenos dias, Catrina!
http://localhost:5000/throw/ooops! “ooops!” 문자열을 사용하여 예외를 throw합니다.
http://localhost:5000/throw “Uh oh!” 문자열을 사용하여 예외를 throw합니다.
http://localhost:5000/Sante/Kevin Sante, Kevin!
http://localhost:5000 Hello World!

WaitForShutdown은 중단(Ctrl-C/SIGINT 또는 SIGTERM)이 발생할 때까지 차단합니다. 앱은 Console.WriteLine 메시지를 표시하고 종료하기 위한 키 입력을 대기합니다.

Start(string url, Action<IRouteBuilder> routeBuilder)

URL 및 IRouteBuilder의 인스턴스를 사용합니다.

using (var host = WebHost.Start("http://localhost:8080", router => router
    .MapGet("hello/{name}", (req, res, data) => 
        res.WriteAsync($"Hello, {data.Values["name"]}!"))
    .MapGet("buenosdias/{name}", (req, res, data) => 
        res.WriteAsync($"Buenos dias, {data.Values["name"]}!"))
    .MapGet("throw/{message?}", (req, res, data) => 
        throw new Exception((string)data.Values["message"] ?? "Uh oh!"))
    .MapGet("{greeting}/{name}", (req, res, data) => 
        res.WriteAsync($"{data.Values["greeting"]}, {data.Values["name"]}!"))
    .MapGet("", (req, res, data) => res.WriteAsync("Hello, World!"))))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

앱이 http://localhost:8080에서 응답한다는 점을 제외하고 Start(Action<IRouteBuilder> routeBuilder)와 동일한 결과가 생성됩니다.

StartWith(Action<IApplicationBuilder> app)

대리자를 제공하여 IApplicationBuilder를 구성합니다.

using (var host = WebHost.StartWith(app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

중단(Ctrl-C/SIGINT 또는 SIGTERM)이 발생할 때까지 브라우저에서 http://localhost:5000이 응답 "Hello World!" WaitForShutdown 블록을 수신하도록 요청합니다. 앱은 Console.WriteLine 메시지를 표시하고 종료하기 위한 키 입력을 대기합니다.

StartWith(string url, Action<IApplicationBuilder> app)

URL 및 대리자를 제공하여 IApplicationBuilder를 구성합니다.

using (var host = WebHost.StartWith("http://localhost:8080", app => 
    app.Use(next => 
    {
        return async context => 
        {
            await context.Response.WriteAsync("Hello World!");
        };
    })))
{
    Console.WriteLine("Use Ctrl-C to shut down the host...");
    host.WaitForShutdown();
}

앱이 http://localhost:8080에서 응답한다는 점을 제외하고 StartWith(Action<IApplicationBuilder> app)와 동일한 결과가 생성됩니다.

IWebHostEnvironment 인터페이스

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

public class CustomFileReader
{
    private readonly IWebHostEnvironment _env;

    public CustomFileReader(IWebHostEnvironment env)
    {
        _env = env;
    }

    public string ReadFile(string filePath)
    {
        var fileProvider = _env.WebRootFileProvider;
        // Process the file here
    }
}

규칙 기반 접근 방식은 시작할 때 환경에 따라 앱을 구성하는 데 사용할 수 있습니다. 또는 ConfigureServices에서 사용할 수 있도록 IWebHostEnvironmentStartup 생성자에 주입합니다.

public class Startup
{
    public Startup(IWebHostEnvironment env)
    {
        HostingEnvironment = env;
    }

    public IWebHostEnvironment HostingEnvironment { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        if (HostingEnvironment.IsDevelopment())
        {
            // Development configuration
        }
        else
        {
            // Staging/Production configuration
        }

        var contentRootPath = HostingEnvironment.ContentRootPath;
    }
}

참고 항목

IsDevelopment 확장 메서드 외에 IWebHostEnvironmentIsStaging, IsProductionIsEnvironment(string environmentName) 메서드를 제공합니다. 자세한 내용은 ASP.NET Core에서 여러 환경 사용을 참조하세요.

또한 IWebHostEnvironment 서비스를 파이프라인 처리를 설정하기 위한 Configure 메서드에 직접 주입할 수 있습니다.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // In Development, use the Developer Exception Page
        app.UseDeveloperExceptionPage();
    }
    else
    {
        // In Staging/Production, route exceptions to /error
        app.UseExceptionHandler("/error");
    }

    var contentRootPath = env.ContentRootPath;
}

사용자 지정 미들웨어를 만들 때 IWebHostEnvironmentInvoke 메서드에 주입할 수 있습니다.

public async Task Invoke(HttpContext context, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        // Configure middleware for Development
    }
    else
    {
        // Configure middleware for Staging/Production
    }

    var contentRootPath = env.ContentRootPath;
}

IHostApplicationLifetime 인터페이스

IHostApplicationLifetime은 시작 후 및 종료 작업을 허용합니다. 인터페이스에서 세 가지 속성은 취소 토큰으로, 시작 및 종료 이벤트를 정의하는 Action 메서드를 등록하는 데 사용됩니다.

취소 토큰 트리거되는 경우…
ApplicationStarted 호스트가 완벽하게 시작되었습니다.
ApplicationStopped 호스트가 정상적으로 종료되었습니다. 모든 요청이 처리되어야 합니다. 종료는 이 이벤트가 완료될 때까지 차단합니다.
ApplicationStopping 호스트가 정상적으로 종료되고 있습니다. 요청은 계속 처리할 수 있습니다. 종료는 이 이벤트가 완료될 때까지 차단합니다.
public class Startup
{
    public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
    {
        appLifetime.ApplicationStarted.Register(OnStarted);
        appLifetime.ApplicationStopping.Register(OnStopping);
        appLifetime.ApplicationStopped.Register(OnStopped);

        Console.CancelKeyPress += (sender, eventArgs) =>
        {
            appLifetime.StopApplication();
            // Don't terminate the process immediately, wait for the Main thread to exit gracefully.
            eventArgs.Cancel = true;
        };
    }

    private void OnStarted()
    {
        // Perform post-startup activities here
    }

    private void OnStopping()
    {
        // Perform on-stopping activities here
    }

    private void OnStopped()
    {
        // Perform post-stopped activities here
    }
}

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

public class MyClass
{
    private readonly IHostApplicationLifetime _appLifetime;

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

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

범위 유효성 검사

앱의 환경이 개발인 경우 CreateDefaultBuilderServiceProviderOptions.ValidateScopestrue로 설정합니다.

ValidateScopestrue로 설정된 경우 기본 서비스 공급자는 다음을 확인하기 위해 검사를 수행합니다.

  • 범위가 지정된 서비스는 직접 또는 간접적으로 루트 서비스 공급자에서 해결되지 않습니다.
  • 범위가 지정된 서비스는 직접 또는 간접적으로 싱글톤에 삽입되지 않습니다.

루트 서비스 공급자는 BuildServiceProvider를 호출할 때 만들어집니다. 루트 서비스 공급자의 수명은 공급자가 앱과 함께 시작되고 앱이 종료될 때 삭제되는 앱/서버의 수명에 해당합니다.

범위가 지정된 서비스는 서비스를 만든 컨테이너에 의해 삭제됩니다. 범위가 지정된 서비스가 루트 컨테이너에서 만들어지는 경우 서비스의 수명은 사실상 싱글톤으로 승격됩니다. 해당 서비스는 앱/서버가 종료될 때 루트 컨테이너에 의해서만 삭제되기 때문입니다. 서비스 범위의 유효성 검사는 BuildServiceProvider가 호출될 경우 이러한 상황을 감지합니다.

프로덕션 환경을 포함하여 범위의 유효성을 항상 검사하려면 호스트 작성기에서 with UseDefaultServiceProvider 를 구성 ServiceProviderOptions 합니다.

WebHost.CreateDefaultBuilder(args)
    .UseDefaultServiceProvider((context, options) => {
        options.ValidateScopes = true;
    })

추가 리소스