ASP.NET Core 기본 사항ASP.NET Core fundamentals

이 문서에서는 ASP.NET Core 앱을 개발하는 방법을 이해하는 데 도움이 되는 주요 토픽의 개요를 제공합니다.This article provides an overview of key topics for understanding how to develop ASP.NET Core apps.

Startup 클래스The Startup class

Startup 클래스에서는 다음을 수행합니다.The Startup class is where:

  • 앱에서 요구하는 서비스가 구성됩니다.Services required by the app are configured.
  • 앱의 요청 처리 파이프라인이 일련의 미들웨어 구성 요소로 정의됩니다.The app's request handling pipeline is defined, as a series of middleware components.

샘플 Startup 클래스는 다음과 같습니다.Here's a sample Startup class:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<RazorPagesMovieContext>(options =>
            options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));

        services.AddControllersWithViews();
        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapDefaultControllerRoute();
            endpoints.MapRazorPages();
        });
    }
}

자세한 내용은 ASP.NET Core에서 앱 시작를 참조하세요.For more information, see ASP.NET Core에서 앱 시작.

종속성 주입(서비스)Dependency injection (services)

ASP.NET Core는 구성된 서비스를 앱을 통해 사용할 수 있도록 만드는 기본 제공 DI(종속성 주입) 프레임워크를 포함합니다.ASP.NET Core includes a built-in dependency injection (DI) framework that makes configured services available throughout an app. 예를 들어 로깅 구성 요소는 서비스입니다.For example, a logging component is a service.

서비스를 구성(또는 등록)하는 코드는 Startup.ConfigureServices 메서드에 추가됩니다.Code to configure (or register) services is added to the Startup.ConfigureServices method. 예를 들어:For example:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<RazorPagesMovieContext>(options =>
        options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));

    services.AddControllersWithViews();
    services.AddRazorPages();
}

서비스는 일반적으로 DI로부터 생성자 주입을 사용하여 확인됩니다.Services are typically resolved from DI using constructor injection. 생성자 주입에서는 클래스가 필요한 형식 또는 인터페이스의 생성자 매개 변수를 선언합니다.With constructor injection, a class declares a constructor parameter of either the required type or an interface. DI 프레임워크가 런타임에 이 서비스의 인스턴스를 제공합니다.The DI framework provides an instance of this service at runtime.

다음 예제에서는 생성자 주입을 사용하여 DI로부터 RazorPagesMovieContext를 확인합니다.The following example uses constructor injection to resolve a RazorPagesMovieContext from DI:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;

    public IndexModel(RazorPagesMovieContext context)
    {
        _context = context;
    }

    // ...

    public async Task OnGetAsync()
    {
        Movies = await _context.Movies.ToListAsync();
    }
}

기본 제공 IoC(Inversion of Control) 컨테이너가 앱의 모든 요구 사항을 충족하지 않을 경우 대신 타사 IoC 컨테이너를 사용할 수 있습니다.If the built-in Inversion of Control (IoC) container doesn't meet all of an app's needs, a third-party IoC container can be used instead.

자세한 내용은 ASP.NET Core에서 종속성 주입를 참조하세요.For more information, see ASP.NET Core에서 종속성 주입.

미들웨어Middleware

요청 처리 파이프라인은 일련의 미들웨어 구성 요소로 구성됩니다.The request handling pipeline is composed as a series of middleware components. 각 구성 요소는 HttpContext에 대해 작업을 수행한 후 파이프라인에 있는 다음 미들웨어를 호출하거나 요청을 종료합니다.Each component performs operations on an HttpContext and either invokes the next middleware in the pipeline or terminates the request.

규칙에 따라 미들웨어 구성 요소는 Startup.Configure 메서드에서 Use... 확장 메서드를 호출하여 파이프라인에 추가됩니다.By convention, a middleware component is added to the pipeline by invoking a Use... extension method in the Startup.Configure method. 예를 들어 정적 파일을 렌더링하도록 설정하려면 UseStaticFiles를 호출합니다.For example, to enable rendering of static files, call UseStaticFiles.

다음 예제에서는 요청 처리 파이프라인을 구성합니다.The following example configures a request handling pipeline:

public void Configure(IApplicationBuilder app)
{
    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
        endpoints.MapRazorPages();
    });
}

ASP.NET Core는 풍부한 일련의 기본 제공 미들웨어를 포함합니다.ASP.NET Core includes a rich set of built-in middleware. 사용자 지정 미들웨어 구성 요소를 작성할 수도 있습니다.Custom middleware components can also be written.

자세한 내용은 ASP.NET Core 미들웨어 기본 사항를 참조하세요.For more information, see ASP.NET Core 미들웨어 기본 사항.

호스트Host

ASP.NET Core 앱은 시작 시 ‘호스트’를 빌드합니다.On startup, an ASP.NET Core app builds a host. 호스트는 다음과 같은 앱의 리소스를 모두 캡슐화합니다.The host encapsulates all of the app's resources, such as:

  • HTTP 서버 구현An HTTP server implementation
  • 미들웨어 구성 요소Middleware components
  • 로깅Logging
  • DI(종속성 주입) 서비스Dependency injection (DI) services
  • ConfigurationConfiguration

호스트에는 다음 두 가지가 있습니다.There are two different hosts:

  • .NET 일반 호스트.NET Generic Host
  • ASP.NET Core 웹 호스트ASP.NET Core Web Host

.NET 일반 호스트를 사용하는 것이 좋습니다.The .NET Generic Host is recommended. ASP.NET Core 웹 호스트는 이전 버전과의 호환성을 위해서만 제공됩니다.The ASP.NET Core Web Host is available only for backwards compatibility.

다음 예제에서는 .NET 일반 호스트를 만듭니다.The following example creates a .NET Generic Host:

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

CreateDefaultBuilderConfigureWebHostDefaults 메서드는 다음과 같은 기본 옵션으로 호스트를 구성합니다.The CreateDefaultBuilder and ConfigureWebHostDefaults methods configure a host with a set of default options, such as:

  • Kestrel을 웹 서버로 사용하고 IIS 통합을 설정합니다.Use Kestrel as the web server and enable IIS integration.
  • appsettings.json, appsettings.{Environment Name}.json, 환경 변수, 명령줄 인수 및 기타 구성 소스의 구성을 로드합니다.Load configuration from appsettings.json, appsettings.{Environment Name}.json, environment variables, command line arguments, and other configuration sources.
  • 콘솔 및 디버그 공급자에게 로깅 출력을 보냅니다.Send logging output to the console and debug providers.

자세한 내용은 ASP.NET Core의 .NET 일반 호스트를 참조하세요.For more information, see ASP.NET Core의 .NET 일반 호스트.

비 웹 시나리오Non-web scenarios

제네릭 호스트를 통해 다른 형식의 앱에서 로깅, DI(종속성 주입), 구성 및 앱 수명 관리와 같은 교차 프레임워크 확장을 사용할 수 있습니다.The Generic Host allows other types of apps to use cross-cutting framework extensions, such as logging, dependency injection (DI), configuration, and app lifetime management. 자세한 내용은 ASP.NET Core의 .NET 일반 호스트ASP.NET Core에서 호스팅되는 서비스를 사용하는 백그라운드 작업를 참조하세요.For more information, see ASP.NET Core의 .NET 일반 호스트 and ASP.NET Core에서 호스팅되는 서비스를 사용하는 백그라운드 작업.

서버Servers

ASP.NET Core 앱은 HTTP 요청을 수신하기 위해 HTTP 서버 구현을 사용합니다.An ASP.NET Core app uses an HTTP server implementation to listen for HTTP requests. 해당 서버는 HttpContext에 구성된 일련의 요청 기능으로 앱에 대한 요청을 표시합니다.The server surfaces requests to the app as a set of request features composed into an HttpContext.

ASP.NET Core는 다음과 같은 서버 구현을 제공합니다.ASP.NET Core provides the following server implementations:

  • Kestrel은 플랫폼 간 웹 서버입니다.Kestrel is a cross-platform web server. Kestrel은 보통 IIS를 사용하여 역방향 프록시 구성에서 실행됩니다.Kestrel is often run in a reverse proxy configuration using IIS. Kestrel은 ASP.NET Core 2.0 이상에서 인터넷에 직접 공개되는 공용 연결 에지 서버로 실행할 수도 있습니다.In ASP.NET Core 2.0 or later, Kestrel can be run as a public-facing edge server exposed directly to the Internet.
  • ‘IIS HTTP 서버’는 IIS를 사용하는 Windows용 서버입니다.IIS HTTP Server is a server for Windows that uses IIS. 이 서버를 사용하면 ASP.NET Core 앱 및 IIS는 동일한 프로세스에서 실행됩니다.With this server, the ASP.NET Core app and IIS run in the same process.
  • HTTP.sys는 IIS에서 사용되지 않는 Windows용 서버입니다.HTTP.sys is a server for Windows that isn't used with IIS.

자세한 내용은 ASP.NET Core의 웹 서버 구현를 참조하세요.For more information, see ASP.NET Core의 웹 서버 구현.

ConfigurationConfiguration

ASP.NET Core는 정렬된 일련의 구성 공급 기업에서 이름-값 쌍으로 설정을 가져오는 구성 프레임워크를 제공합니다.ASP.NET Core provides a configuration framework that gets settings as name-value pairs from an ordered set of configuration providers. .json 파일, .xml 파일, 환경 변수 및 명령줄 인수와 같은 다양한 소스에서 기본 제공 구성 공급자를 사용할 수 있습니다.Built-in configuration providers are available for a variety of sources, such as .json files, .xml files, environment variables, and command-line arguments. 다른 소스를 지원하려면 사용자 지정 구성 공급자를 작성하세요.Write custom configuration providers to support other sources.

기본적으로 ASP.NET Core 앱은 appsettings.json, 환경 변수, 명령줄 등에서 읽도록 구성되어 있습니다.By default, ASP.NET Core apps are configured to read from appsettings.json, environment variables, the command line, and more. 앱의 구성이 로드되면 환경 변수의 값이 appsettings.json의 값을 재정의합니다.When the app's configuration is loaded, values from environment variables override values from appsettings.json.

관련 구성 값을 읽는 기본 방법은 옵션 패턴를 사용하는 것입니다.The preferred way to read related configuration values is using the options pattern. 자세한 내용은 Bind hierarchical configuration data using the options pattern(옵션 패턴을 사용하여 계층적 구성 데이터 바인딩)을 참조하세요.For more information, see Bind hierarchical configuration data using the options pattern.

ASP.NET Core는 암호와 같은 기밀 구성 데이터의 관리를 위해 비밀 관리자를 제공합니다.For managing confidential configuration data such as passwords, ASP.NET Core provides the Secret Manager. 프로덕션 비밀의 경우 Azure Key Vault를 사용하는 것이 좋습니다.For production secrets, we recommend Azure Key Vault.

자세한 내용은 ASP.NET Core의 구성를 참조하세요.For more information, see ASP.NET Core의 구성.

환경Environments

Development, StagingProduction과 같은 실행 환경은 ASP.NET Core의 일급 개념입니다.Execution environments, such as Development, Staging, and Production, are a first-class notion in ASP.NET Core. ASPNETCORE_ENVIRONMENT 환경 변수를 설정하여 앱을 실행 중인 환경을 지정합니다.Specify the environment an app is running in by setting the ASPNETCORE_ENVIRONMENT environment variable. ASP.NET Core는 앱 시작 시 해당 환경 변수를 읽고 IWebHostEnvironment 구현에서 값을 저장합니다.ASP.NET Core reads that environment variable at app startup and stores the value in an IWebHostEnvironment implementation. 이 구현은 DI(종속성 주입)를 통해 앱의 어디서나 사용할 수 있습니다.This implementation is available anywhere in an app via dependency injection (DI).

다음 예제에서는 앱이 Development 환경에서 실행될 때 상세한 오류 정보를 제공하도록 구성합니다.The following example configures the app to provide detailed error information when running in the Development environment:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
        endpoints.MapRazorPages();
    });
}

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

로깅Logging

ASP.NET Core는 다양한 기본 제공 및 타사 로깅 공급자와 함께 작동하는 로깅 API를 지원합니다.ASP.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. 사용 가능한 공급자는 다음과 같습니다.Available providers include:

  • ConsoleConsole
  • 디버그Debug
  • Windows 이벤트 추적Event Tracing on Windows
  • Windows 이벤트 로그Windows Event Log
  • TraceSourceTraceSource
  • Azure App ServiceAzure App Service
  • Azure Application InsightsAzure Application Insights

로그를 만들려면 DI(종속성 주입)로부터 ILogger<TCategoryName> 서비스를 확인하고 LogInformation과 같은 로깅 메서드를 호출합니다.To create logs, resolve an ILogger<TCategoryName> service from dependency injection (DI) and call logging methods such as LogInformation. 예를 들어:For example:

public class TodoController : ControllerBase
{
    private readonly ILogger _logger;

    public TodoController(ILogger<TodoController> logger)
    {
        _logger = logger;
    }

    [HttpGet("{id}", Name = "GetTodo")]
    public ActionResult<TodoItem> GetById(string id)
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        
        // Item lookup code removed.
        
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
        
        return item;
    }
}

LogInformation과 같은 로깅 메서드는 임의 개수의 필드를 지원합니다.Logging methods such as LogInformation support any number of fields. 필드는 일반적으로 메시지 string을 생성하는 데 사용되지만 일부 로깅 공급자는 이들 필드를 별도의 필드로 데이터 저장소로 보냅니다.These fields are commonly used to construct a message string, but some logging providers send these to a data store as separate fields. 이 기능을 사용하면 로그 공급 기업이 구조적 로깅이라고도 하는 의미 체계 로깅을 구현할 수 있게 됩니다.This feature makes it possible for logging providers to implement semantic logging, also known as structured logging.

자세한 내용은 .NET Core 및 ASP.NET Core의 로깅를 참조하세요.For more information, see .NET Core 및 ASP.NET Core의 로깅.

라우팅Routing

경로는 처리기에 매핑되는 URL 패턴입니다.A route is a URL pattern that is mapped to a handler. 처리기는 일반적으로 Razor Page, MVC 컨트롤러의 작업 메서드 또는 미들웨어와 같습니다.The handler is typically a Razor page, an action method in an MVC controller, or a middleware. ASP.NET Core 라우팅을 사용하면 앱에서 사용되는 URL을 제어할 수 있습니다.ASP.NET Core routing gives you control over the URLs used by your app.

자세한 내용은 ASP.NET Core에서 라우팅를 참조하세요.For more information, see ASP.NET Core에서 라우팅.

오류 처리Error handling

ASP.NET Core에는 다음과 같은 오류를 처리하기 위한 기본 제공 기능이 포함됩니다.ASP.NET Core has built-in features for handling errors, such as:

  • 개발자 예외 페이지A developer exception page
  • 사용자 지정 오류 페이지Custom error pages
  • 정적 상태 코드 페이지Static status code pages
  • 시작 예외 처리Startup exception handling

자세한 내용은 ASP.NET Core에서 오류 처리를 참조하세요.For more information, see ASP.NET Core에서 오류 처리.

HTTP 요청 만들기Make HTTP requests

HttpClient 인스턴스를 만들기 위해 IHttpClientFactory를 구현할 수 있습니다.An implementation of IHttpClientFactory is available for creating HttpClient instances. 팩터리는 다음과 같습니다.The factory:

  • 논리적 HttpClient 인스턴스를 구성하고 이름을 지정하기 위한 중앙 위치를 제공합니다.Provides a central location for naming and configuring logical HttpClient instances. 예를 들어, GitHub에 액세스하는 github 클라이언트를 등록 및 구성합니다.For example, register and configure a github client for accessing GitHub. 다른 용도를 위한 기본 클라이언트를 등록 및 구성합니다.Register and configure a default client for other purposes.
  • 나가는 요청 미들웨어 파이프라인을 빌드하기 위해 여러 위임 처리기를 연결하고 등록하도록 지원합니다.Supports registration and chaining of multiple delegating handlers to build an outgoing request middleware pipeline. 이 패턴은 ASP.NET Core의 인바운드 미들웨어 파이프라인과 비슷합니다.This pattern is similar to ASP.NET Core's inbound middleware pipeline. 이 패턴은 캐싱, 오류 처리, serialization 및 로깅을 포함한 HTTP 요청 관련 횡단 문제를 관리하기 위한 메커니즘을 제공합니다.The pattern provides a mechanism to manage cross-cutting concerns for HTTP requests, including caching, error handling, serialization, and logging.
  • 일시적인 오류를 처리하기 위해 널리 사용되는 타사 라이브러리인 Polly와 통합합니다.Integrates with Polly, a popular third-party library for transient fault handling.
  • HttpClient 수명을 수동으로 관리할 때 발생하는 일반적인 DNS 문제를 피하기 위해 기본 HttpClientHandler 인스턴스의 풀링 및 수명을 관리합니다.Manages the pooling and lifetime of underlying HttpClientHandler instances to avoid common DNS problems that occur when managing HttpClient lifetimes manually.
  • 팩터리에서 만든 클라이언트를 통해 전송된 모든 요청에 대해 ILogger를 통해 구성 가능한 로깅 환경을 추가합니다.Adds a configurable logging experience via ILogger for all requests sent through clients created by the factory.

자세한 내용은 ASP.NET Core에서 IHttpClientFactory를 사용하여 HTTP 요청 만들기를 참조하세요.For more information, see ASP.NET Core에서 IHttpClientFactory를 사용하여 HTTP 요청 만들기.

콘텐츠 루트Content root

콘텐츠 루트는 다음의 기본 경로입니다.The content root is the base path for:

  • 앱을 호스트하는 실행 파일( .exe)The executable hosting the app (.exe).
  • 앱을 구성하는 컴파일된 어셈블리( .dll)Compiled assemblies that make up the app (.dll).
  • 앱에서 사용하는 다음과 같은 콘텐츠 파일:Content files used by the app, such as:
    • Razor 파일( .cshtml, .razor)Razor files (.cshtml, .razor)
    • 구성 파일( .json, .xml)Configuration files (.json, .xml)
    • 데이터 파일( .db)Data files (.db)
  • 웹 루트(일반적으로 wwwroot 폴더)The Web root, typically the wwwroot folder.

개발 중에는 콘텐츠 루트가 기본적으로 프로젝트의 루트 디렉터리로 설정됩니다.During development, the content root defaults to the project's root directory. 이 디렉터리는 앱의 콘텐츠 파일과 웹 루트의 기본 경로이기도 합니다.This directory is also the base path for both the app's content files and the Web root. 호스트를 빌드할 때는 경로를 설정하여 다른 콘텐츠 루트를 지정하세요.Specify a different content root by setting its path when building the host. 자세한 내용은 콘텐츠 루트를 참조하세요.For more information, see Content root.

웹 루트Web root

웹 루트는 다음과 같은 퍼블릭 정적 리소스 파일의 기본 경로입니다.The web root is the base path for public, static resource files, such as:

  • 스타일시트( .css)Stylesheets (.css)
  • JavaScript( .js)JavaScript (.js)
  • 이미지( .png, .jpg)Images (.png, .jpg)

정적 파일은 기본적으로 웹 루트 디렉터리와 그 하위 디렉터리에서만 제공됩니다.By default, static files are served only from the web root directory and its sub-directories. 웹 루트 경로는 기본적으로 {content root}/wwwroot로 설정됩니다.The web root path defaults to {content root}/wwwroot. 호스트를 빌드할 때는 경로를 설정하여 다른 웹 루트를 지정하세요.Specify a different web root by setting its path when building the host. 자세한 내용은 웹 루트를 참조하세요.For more information, see Web root.

프로젝트 파일에서 <Content> 프로젝트 항목을 사용하여 wwwroot에 파일을 게시하지 못하도록 합니다.Prevent publishing files in wwwroot with the <Content> project item in the project file. 다음 예제에서는 wwwroot/local과 그 하위 디렉터리에서 콘텐츠가 게시되지 못하도록 합니다.The following example prevents publishing content in wwwroot/local and its sub-directories:

<ItemGroup>
  <Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>

Razor .cshtml 파일에서는 물결표 슬래시(~/)가 웹 루트를 가리킵니다.In Razor .cshtml files, tilde-slash (~/) points to the web root. ~/(으)로 시작하는 경로를 가상 경로라고 합니다.A path beginning with ~/ is referred to as a virtual path.

자세한 내용은 ASP.NET Core의 정적 파일를 참조하세요.For more information, see ASP.NET Core의 정적 파일.

이 문서는 ASP.NET Core 앱을 개발하는 방법을 이해하기 위한 주요 항목의 개요입니다.This article is an overview of key topics for understanding how to develop ASP.NET Core apps.

Startup 클래스The Startup class

Startup 클래스에서는 다음을 수행합니다.The Startup class is where:

  • 앱에서 요구하는 서비스가 구성됩니다.Services required by the app are configured.
  • 요청 처리 파이프라인이 정의됩니다.The request handling pipeline is defined.

서비스는 앱에서 사용되는 구성 요소입니다.Services are components that are used by the app. 예를 들어 로깅 구성 요소는 서비스입니다.For example, a logging component is a service. 서비스를 구성(또는 등록)하는 코드는 Startup.ConfigureServices 메서드에 추가됩니다.Code to configure (or register) services is added to the Startup.ConfigureServices method.

요청 처리 파이프라인은 일련의 미들웨어 구성 요소로 구성됩니다.The request handling pipeline is composed as a series of middleware components. 예를 들어 미들웨어는 정적 파일에 대한 요청을 처리하거나 HTTP 요청을 HTTPS로 리디렉션할 수 있습니다.For example, a middleware might handle requests for static files or redirect HTTP requests to HTTPS. 각 미들웨어는 HttpContext 상에서 비동기 작업을 수행한 다음, 파이프라인의 다음 미들웨어를 호출하거나 요청을 종료합니다.Each middleware performs asynchronous operations on an HttpContext and then either invokes the next middleware in the pipeline or terminates the request. 요청 처리 파이프라인을 구성하는 코드는 Startup.Configure 메서드에 추가됩니다.Code to configure the request handling pipeline is added to the Startup.Configure method.

샘플 Startup 클래스는 다음과 같습니다.Here's a sample Startup class:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        services.AddDbContext<MovieContext>(options =>
                options.UseSqlServer(Configuration.GetConnectionString("MovieDb")));
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseMvc();
    }
}

자세한 내용은 ASP.NET Core에서 앱 시작를 참조하세요.For more information, see ASP.NET Core에서 앱 시작.

종속성 주입(서비스)Dependency injection (services)

ASP.NET Core에는 구성된 서비스를 앱의 클래스에 사용할 수 있도록 만드는 기본 제공 DI(종속성 주입) 프레임워크가 포함됩니다.ASP.NET Core has a built-in dependency injection (DI) framework that makes configured services available to an app's classes. 클래스에서 서비스의 인스턴스를 가져오는 한 가지 방법은 필수 형식의 매개 변수를 사용하여 생성자를 만드는 것입니다.One way to get an instance of a service in a class is to create a constructor with a parameter of the required type. 해당 매개 변수는 서비스 형식 또는 인터페이스일 수 있습니다.The parameter can be the service type or an interface. DI 시스템에서는 런타임 시 서비스를 제공합니다.The DI system provides the service at runtime.

Entity Framework Core 컨텍스트 개체를 가져오는 데 DI를 사용하는 클래스는 다음과 같습니다.Here's a class that uses DI to get an Entity Framework Core context object. 강조 표시된 줄은 생성자 주입의 예제입니다.The highlighted line is an example of constructor injection:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;

    public IndexModel(RazorPagesMovieContext context)
    {
        _context = context;
    }

    // ...

    public async Task OnGetAsync()
    {
        Movies = await _context.Movies.ToListAsync();
    }
}

DI가 기본 제공되기는 하지만 원하는 경우 타사 IoC(Inversion of Control) 컨테이너를 플러그 인할 수 있도록 설계되었습니다.While DI is built in, it's designed to let you plug in a third-party Inversion of Control (IoC) container if you prefer.

자세한 내용은 ASP.NET Core에서 종속성 주입를 참조하세요.For more information, see ASP.NET Core에서 종속성 주입.

미들웨어Middleware

요청 처리 파이프라인은 일련의 미들웨어 구성 요소로 구성됩니다.The request handling pipeline is composed as a series of middleware components. 각 구성 요소는 HttpContext 상에서 비동기 작업을 수행한 다음, 파이프라인의 다음 미들웨어를 호출하거나 요청을 종료합니다.Each component performs asynchronous operations on an HttpContext and then either invokes the next middleware in the pipeline or terminates the request.

규칙에 따라 미들웨어 구성 요소는 Startup.Configure 메서드에서 Use... 확장 메서드를 호출하여 파이프라인에 추가됩니다.By convention, a middleware component is added to the pipeline by invoking its Use... extension method in the Startup.Configure method. 예를 들어 정적 파일을 렌더링하도록 설정하려면 UseStaticFiles를 호출합니다.For example, to enable rendering of static files, call UseStaticFiles.

다음 예제에서 강조 표시된 코드는 요청 처리 파이프라인을 구성합니다.The highlighted code in the following example configures the request handling pipeline:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        services.AddDbContext<MovieContext>(options =>
                options.UseSqlServer(Configuration.GetConnectionString("MovieDb")));
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseMvc();
    }
}

ASP.NET Core는 풍부한 일련의 기본 제공 미들웨어를 포함하고 있으며, 사용자 지정 미들웨어를 작성할 수 있습니다.ASP.NET Core includes a rich set of built-in middleware, and you can write custom middleware.

자세한 내용은 ASP.NET Core 미들웨어 기본 사항를 참조하세요.For more information, see ASP.NET Core 미들웨어 기본 사항.

호스트Host

ASP.NET Core 앱은 시작 시 호스트를 빌드합니다.An ASP.NET Core app builds a host on startup. 호스트는 다음과 같은 앱의 리소스를 모두 캡슐화하는 개체입니다.The host is an object that encapsulates all of the app's resources, such as:

  • HTTP 서버 구현An HTTP server implementation
  • 미들웨어 구성 요소Middleware components
  • 로깅Logging
  • DIDI
  • ConfigurationConfiguration

하나의 개체에 앱의 모든 상호 종속적 리소스를 포함하는 주요 원인은 수명 관리 즉, 앱 시작 및 종료에 대한 제어 때문입니다.The main reason for including all of the app's interdependent resources in one object is lifetime management: control over app startup and graceful shutdown.

두 호스트, 웹 호스트와 제네릭 호스트를 사용할 수 있습니다.Two hosts are available: the Web Host and the Generic Host. ASP.NET Core 2.x에서 제네릭 호스트는 비 웹 시나리오에만 해당됩니다.In ASP.NET Core 2.x, the Generic Host is only for non-web scenarios.

호스트를 만드는 코드는 Program.Main에 있습니다.The code to create a host is in Program.Main:

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 메서드는 다음과 같이 일반적으로 사용되는 옵션으로 호스트를 구성합니다.The CreateDefaultBuilder method configures a host with commonly used options, such as the following:

  • Kestrel을 웹 서버로 사용하고 IIS 통합을 설정합니다.Use Kestrel as the web server and enable IIS integration.
  • appsettings.json, appsettings.{Environment Name}.json, 환경 변수, 명령줄 인수 및 기타 구성 소스의 구성을 로드합니다.Load configuration from appsettings.json, appsettings.{Environment Name}.json, environment variables, command line arguments, and other configuration sources.
  • 콘솔 및 디버그 공급자에게 로깅 출력을 보냅니다.Send logging output to the console and debug providers.

자세한 내용은 ASP.NET Core 웹 호스트를 참조하세요.For more information, see ASP.NET Core 웹 호스트.

비 웹 시나리오Non-web scenarios

제네릭 호스트를 통해 다른 형식의 앱에서 로깅, DI(종속성 주입), 구성 및 앱 수명 관리와 같은 교차 프레임워크 확장을 사용할 수 있습니다.The Generic Host allows other types of apps to use cross-cutting framework extensions, such as logging, dependency injection (DI), configuration, and app lifetime management. 자세한 내용은 ASP.NET Core의 .NET 일반 호스트ASP.NET Core에서 호스팅되는 서비스를 사용하는 백그라운드 작업를 참조하세요.For more information, see ASP.NET Core의 .NET 일반 호스트 and ASP.NET Core에서 호스팅되는 서비스를 사용하는 백그라운드 작업.

서버Servers

ASP.NET Core 앱은 HTTP 요청을 수신하기 위해 HTTP 서버 구현을 사용합니다.An ASP.NET Core app uses an HTTP server implementation to listen for HTTP requests. 해당 서버는 HttpContext에 구성된 일련의 요청 기능으로 앱에 대한 요청을 표시합니다.The server surfaces requests to the app as a set of request features composed into an HttpContext.

ASP.NET Core는 다음과 같은 서버 구현을 제공합니다.ASP.NET Core provides the following server implementations:

  • Kestrel은 플랫폼 간 웹 서버입니다.Kestrel is a cross-platform web server. Kestrel은 보통 IIS를 사용하여 역방향 프록시 구성에서 실행됩니다.Kestrel is often run in a reverse proxy configuration using IIS. Kestrel은 인터넷에 직접 공개되는 공용 연결 에지 서버로 실행할 수도 있습니다.Kestrel can be run as a public-facing edge server exposed directly to the Internet.
  • ‘IIS HTTP 서버’는 IIS를 사용하는 Windows용 서버입니다.IIS HTTP Server is a server for windows that uses IIS. 이 서버를 사용하면 ASP.NET Core 앱 및 IIS는 동일한 프로세스에서 실행됩니다.With this server, the ASP.NET Core app and IIS run in the same process.
  • HTTP.sys는 IIS에서 사용되지 않는 Windows용 서버입니다.HTTP.sys is a server for Windows that isn't used with IIS.

ASP.NET Core는 다음과 같은 서버 구현을 제공합니다.ASP.NET Core provides the following server implementations:

  • Kestrel은 플랫폼 간 웹 서버입니다.Kestrel is a cross-platform web server. Kestrel은 보통 IIS를 사용하여 역방향 프록시 구성에서 실행됩니다.Kestrel is often run in a reverse proxy configuration using IIS. Kestrel은 인터넷에 직접 공개되는 공용 연결 에지 서버로 실행할 수도 있습니다.Kestrel can be run as a public-facing edge server exposed directly to the Internet.
  • HTTP.sys는 IIS에서 사용되지 않는 Windows용 서버입니다.HTTP.sys is a server for Windows that isn't used with IIS.

자세한 내용은 ASP.NET Core의 웹 서버 구현를 참조하세요.For more information, see ASP.NET Core의 웹 서버 구현.

ConfigurationConfiguration

ASP.NET Core는 정렬된 일련의 구성 공급 기업에서 이름-값 쌍으로 설정을 가져오는 구성 프레임워크를 제공합니다.ASP.NET Core provides a configuration framework that gets settings as name-value pairs from an ordered set of configuration providers. .json 파일, .xml 파일, 환경 변수 및 명령줄 인수와 같은 다양한 원본의 기본 제공 구성 공급 기업이 있습니다.There are built-in configuration providers for a variety of sources, such as .json files, .xml files, environment variables, and command-line arguments. 또는 사용자 지정 구성 공급 기업을 작성할 수도 있습니다.You can also write custom configuration providers.

예를 들어 구성이 appsettings.json 및 환경 변수에서 제공되도록 지정할 수 있습니다.For example, you could specify that configuration comes from appsettings.json and environment variables. 그런 다음, ConnectionString 값이 요청되면 프레임워크는 먼저 appsettings.json 파일을 찾습니다.Then when the value of ConnectionString is requested, the framework looks first in the appsettings.json file. 값을 찾았지만 환경 변수에서도 값을 찾을 수 있다면 환경 변수의 값이 우선 적용됩니다.If the value is found there but also in an environment variable, the value from the environment variable would take precedence.

ASP.NET Core는 암호와 같은 기밀 구성 데이터를 관리하기 위해 비밀 관리자 도구를 제공합니다.For managing confidential configuration data such as passwords, ASP.NET Core provides a Secret Manager tool. 프로덕션 비밀의 경우 Azure Key Vault를 사용하는 것이 좋습니다.For production secrets, we recommend Azure Key Vault.

자세한 내용은 ASP.NET Core의 구성를 참조하세요.For more information, see ASP.NET Core의 구성.

옵션Options

가능할 경우 ASP.NET Core는 구성 값을 저장하고 검색하기 위해 옵션 패턴을 따릅니다.Where possible, ASP.NET Core follows the options pattern for storing and retrieving configuration values. 옵션 패턴은 클래스를 사용하여 관련 설정 그룹을 나타냅니다.The options pattern uses classes to represent groups of related settings.

예를 들어 다음 코드에서는 WebSockets 옵션을 설정합니다.For example, the following code sets WebSockets options:

var options = new WebSocketOptions  
{  
   KeepAliveInterval = TimeSpan.FromSeconds(120),  
   ReceiveBufferSize = 4096
};  

app.UseWebSockets(options);

자세한 내용은 ASP.NET Core의 옵션 패턴를 참조하세요.For more information, see ASP.NET Core의 옵션 패턴.

환경Environments

개발, 준비프로덕션과 같은 실행 환경은 ASP.NET Core의 일급 개념입니다.Execution environments, such as Development, Staging, and Production, are a first-class notion in ASP.NET Core. ASPNETCORE_ENVIRONMENT 환경 변수를 설정하여 앱을 실행 중인 환경을 지정할 수 있습니다.You can specify the environment an app is running in by setting the ASPNETCORE_ENVIRONMENT environment variable. ASP.NET Core는 앱 시작 시 해당 환경 변수를 읽고 IHostingEnvironment 구현에서 값을 저장합니다.ASP.NET Core reads that environment variable at app startup and stores the value in an IHostingEnvironment implementation. 환경 개체는 DI를 통해 앱에서 사용할 수 있습니다.The environment object is available anywhere in the app via DI.

Startup 클래스의 다음 샘플 코드는 개발 중에 실행할 때만 자세한 오류 정보를 제공하도록 앱을 구성합니다.The following sample code from the Startup class configures the app to provide detailed error information only when it runs in development:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseMvc();
}

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

로깅Logging

ASP.NET Core는 다양한 기본 제공 및 타사 로깅 공급자와 함께 작동하는 로깅 API를 지원합니다.ASP.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. 지원되는 공급 기업에는 다음이 포함됩니다.Available providers include the following:

  • ConsoleConsole
  • 디버그Debug
  • Windows 이벤트 추적Event Tracing on Windows
  • Windows 이벤트 로그Windows Event Log
  • TraceSourceTraceSource
  • Azure App ServiceAzure App Service
  • Azure Application InsightsAzure Application Insights

DI에서 ILogger 개체를 가져오고 로그 메서드를 호출하여 앱 코드 어디서나 로그를 작성합니다.Write logs from anywhere in an app's code by getting an ILogger object from DI and calling log methods.

생성자 주입 및 로깅 메서드 호출을 강조 표시하고 ILogger 개체를 사용하는 샘플 코드는 다음과 같습니다.Here's sample code that uses an ILogger object, with constructor injection and the logging method calls highlighted.

public class TodoController : ControllerBase
{
    private readonly ILogger _logger;

    public TodoController(ILogger<TodoController> logger)
    {
        _logger = logger;
    }

    [HttpGet("{id}", Name = "GetTodo")]
    public ActionResult<TodoItem> GetById(string id)
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        // Item lookup code removed.
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
        return item;
    }
}

ILogger 인터페이스를 통해 필드 개수에 관계 없이 로그 공급 기업에 전달할 수 있습니다.The ILogger interface lets you pass any number of fields to the logging provider. 필드는 일반적으로 메시지 문자열을 생성하는 데 사용되지만 공급 기업은 이를 별도 필드로 데이터 저장소에 보낼 수도 있습니다.The fields are commonly used to construct a message string, but the provider can also send them as separate fields to a data store. 이 기능을 사용하면 로그 공급 기업이 구조적 로깅이라고도 하는 의미 체계 로깅을 구현할 수 있게 됩니다.This feature makes it possible for logging providers to implement semantic logging, also known as structured logging.

자세한 내용은 .NET Core 및 ASP.NET Core의 로깅를 참조하세요.For more information, see .NET Core 및 ASP.NET Core의 로깅.

라우팅Routing

경로는 처리기에 매핑되는 URL 패턴입니다.A route is a URL pattern that is mapped to a handler. 처리기는 일반적으로 Razor Page, MVC 컨트롤러의 작업 메서드 또는 미들웨어와 같습니다.The handler is typically a Razor page, an action method in an MVC controller, or a middleware. ASP.NET Core 라우팅을 사용하면 앱에서 사용되는 URL을 제어할 수 있습니다.ASP.NET Core routing gives you control over the URLs used by your app.

자세한 내용은 ASP.NET Core에서 라우팅를 참조하세요.For more information, see ASP.NET Core에서 라우팅.

오류 처리Error handling

ASP.NET Core에는 다음과 같은 오류를 처리하기 위한 기본 제공 기능이 포함됩니다.ASP.NET Core has built-in features for handling errors, such as:

  • 개발자 예외 페이지A developer exception page
  • 사용자 지정 오류 페이지Custom error pages
  • 정적 상태 코드 페이지Static status code pages
  • 시작 예외 처리Startup exception handling

자세한 내용은 ASP.NET Core에서 오류 처리를 참조하세요.For more information, see ASP.NET Core에서 오류 처리.

HTTP 요청 만들기Make HTTP requests

HttpClient 인스턴스를 만들기 위해 IHttpClientFactory를 구현할 수 있습니다.An implementation of IHttpClientFactory is available for creating HttpClient instances. 팩터리는 다음과 같습니다.The factory:

  • 논리적 HttpClient 인스턴스를 구성하고 이름을 지정하기 위한 중앙 위치를 제공합니다.Provides a central location for naming and configuring logical HttpClient instances. 예를 들어, github 클라이언트는 GitHub에 액세스하도록 등록 및 구성할 수 있습니다.For example, a github client can be registered and configured to access GitHub. 기본 클라이언트는 다른 용도로 등록할 수 있습니다.A default client can be registered for other purposes.
  • 나가는 요청 미들웨어 파이프라인을 빌드하기 위해 여러 위임 처리기를 연결하고 등록하도록 지원합니다.Supports registration and chaining of multiple delegating handlers to build an outgoing request middleware pipeline. 이 패턴은 ASP.NET Core의 인바운드 미들웨어 파이프라인과 비슷합니다.This pattern is similar to the inbound middleware pipeline in ASP.NET Core. 이 패턴은 캐싱, 오류 처리, 직렬화 및 로깅을 포함한 HTTP 요청을 둘러싼 횡단 관심사를 관리하기 위한 메커니즘을 제공합니다.The pattern provides a mechanism to manage cross-cutting concerns around HTTP requests, including caching, error handling, serialization, and logging.
  • 일시적인 오류를 처리하기 위해 널리 사용되는 타사 라이브러리인 Polly와 통합합니다.Integrates with Polly, a popular third-party library for transient fault handling.
  • HttpClient 수명을 수동으로 관리할 때 발생하는 일반적인 DNS 문제를 피하기 위해 기본 HttpClientHandler 인스턴스의 풀링 및 수명을 관리합니다.Manages the pooling and lifetime of underlying HttpClientHandler instances to avoid common DNS problems that occur when manually managing HttpClient lifetimes.
  • 팩터리에서 만든 클라이언트를 통해 전송된 모든 요청에 대해 구성 가능한 로깅 경험(ILogger을 통해)을 추가합니다.Adds a configurable logging experience (via ILogger) for all requests sent through clients created by the factory.

자세한 내용은 ASP.NET Core에서 IHttpClientFactory를 사용하여 HTTP 요청 만들기를 참조하세요.For more information, see ASP.NET Core에서 IHttpClientFactory를 사용하여 HTTP 요청 만들기.

콘텐츠 루트Content root

콘텐츠 루트는 다음의 기본 경로입니다.The content root is the base path to the:

  • 앱을 호스트하는 실행 파일( .exe)Executable hosting the app (.exe).
  • 앱을 구성하는 컴파일된 어셈블리( .dll)Compiled assemblies that make up the app (.dll).
  • 다음과 같은 앱에서 사용하는 비코드 콘텐츠 파일:Non-code content files used by the app, such as:
    • Razor 파일( .cshtml, .razor)Razor files (.cshtml, .razor)
    • 구성 파일( .json, .xml)Configuration files (.json, .xml)
    • 데이터 파일( .db)Data files (.db)
  • 웹 루트(일반적으로 wwwroot 폴더에 게시됨)Web root, typically the published wwwroot folder.

개발 중:During development:

  • 콘텐츠 루트의 기본값은 프로젝트의 루트 디렉터리입니다.The content root defaults to the project's root directory.
  • 프로젝트의 루트 디렉터리는 다음을 만드는 데 사용됩니다.The project's root directory is used to create the:
    • 프로젝트의 루트 디렉터리에서 앱의 비코드 콘텐츠 파일의 경로Path to the app's non-code content files in the project's root directory.
    • 웹 루트(일반적으로 프로젝트의 루트 디렉터리의 wwwroot 폴더)Web root, typically the wwwroot folder in the project's root directory.

호스트를 빌드할 때 지정될 수 있는 대체 콘텐츠 루트 경로An alternative content root path can be specified when building the host. 자세한 내용은 ASP.NET Core 웹 호스트를 참조하세요.For more information, see ASP.NET Core 웹 호스트.

웹 루트Web root

웹 루트는 다음과 같은 공용, 비코드, 정적 리소스 파일의 기본 경로입니다.The web root is the base path to public, non-code, static resource files, such as:

  • 스타일시트( .css)Stylesheets (.css)
  • JavaScript( .js)JavaScript (.js)
  • 이미지( .png, .jpg)Images (.png, .jpg)

정적 파일은 기본적으로 웹 루트 디렉터리 및 하위 디렉터리에서만 제공됩니다.Static files are only served by default from the web root directory (and sub-directories).

웹 루트 경로는 {content root}/wwwroot를 기본값으로 지정하지만 호스트를 빌드할 때 다른 웹 루트를 지정할 수도 있습니다.The web root path defaults to {content root}/wwwroot, but a different web root can be specified when building the host. 자세한 내용은 웹 루트를 참조하세요.For more information, see Web root.

프로젝트 파일에서 <Content> 프로젝트 항목을 사용하여 wwwroot에 파일을 게시하지 못하도록 합니다.Prevent publishing files in wwwroot with the <Content> project item in the project file. 다음 예에서는 wwwroot/local 디렉터리 및 하위 디렉터리에 콘텐츠를 게시하지 못하도록 합니다.The following example prevents publishing content in the wwwroot/local directory and sub-directories:

<ItemGroup>
  <Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>

Razor( .cshtml) 파일에서는 물결표 슬래시(~/)가 웹 루트를 가리킵니다.In Razor (.cshtml) files, the tilde-slash (~/) points to the web root. ~/(으)로 시작하는 경로를 가상 경로라고 합니다.A path beginning with ~/ is referred to as a virtual path.

자세한 내용은 ASP.NET Core의 정적 파일를 참조하세요.For more information, see ASP.NET Core의 정적 파일.