다음을 통해 공유

ASP.NET Core 기본 사항 개요

  • 아티클

참고 항목

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

Warning

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

Important

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

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

이 문서에서는 DI(종속성 주입), 구성, 미들웨어 등을 포함하여 ASP.NET Core 앱을 빌드하기 위한 기본 사항의 개요를 간략하게 설명합니다.

Blazor 이 노드의 지침을 추가하거나 대체하는 기본 사항 지침은 ASP.NET Core Blazor 기본 사항을 참조하세요.

Program.cs

웹 템플릿으로 만든 ASP.NET Core 앱은 Program.cs 파일에 애플리케이션 시작 코드를 포함합니다. Program.cs 파일은 다음과 같습니다.

  • 앱에서 요구하는 서비스가 구성됩니다.
  • 앱의 요청 처리 파이프라인이 일련의 미들웨어 구성 요소로 정의됩니다.

다음 앱 시작 코드는 다음을 지원합니다.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

종속성 주입(서비스)

ASP.NET Core에는 구성된 서비스를 앱을 통해 사용할 수 있도록 만드는 DI(종속성 주입) 프레임워크가 포함됩니다. 서비스는 위의 코드에서 WebApplicationBuilder.Services, builder.Services를 사용하여 DI 컨테이너에 추가됩니다. WebApplicationBuilder가 인스턴스화되면 프레임워크에서 제공하는 서비스가 다수 추가됩니다. builder는 아래 코드에서 WebApplicationBuilder입니다.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

위의 강조 표시된 코드에서 builder에는 구성, 로깅, 그리고 DI 컨테이너에 추가된 다른 많은 서비스가 있습니다.

다음 코드는 Razor Pages, 뷰가 있는 MVC 컨트롤러 및 사용자 지정 DbContext를 DI 컨테이너에 추가합니다.

using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Data;
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

builder.Services.AddDbContext<RazorPagesMovieContext>(options =>
   options.UseSqlServer(builder.Configuration.GetConnectionString("RPMovieContext")));

var app = builder.Build();

서비스는 일반적으로 DI로부터 생성자 주입을 사용하여 확인됩니다. DI 프레임워크가 런타임에 이 서비스의 인스턴스를 제공합니다.

다음 코드는 생성자 주입을 사용하여 DI에서 데이터베이스 컨텍스트 및 로거를 확인합니다.

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

미들웨어

요청 처리 파이프라인은 일련의 미들웨어 구성 요소로 구성됩니다. 각 구성 요소는 HttpContext에 대해 작업을 수행한 후 파이프라인에 있는 다음 미들웨어를 호출하거나 요청을 종료합니다.

규칙에 따라 미들웨어 구성 요소는 Use{Feature} 확장 메서드를 호출하여 파이프라인에 추가됩니다. 앱에 추가된 미들웨어가 다음 코드에서 강조 표시되어 있습니다.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

자세한 내용은 ASP.NET Core 미들웨어를 참조하세요.

호스트

ASP.NET Core 앱은 시작 시 ‘호스트’를 빌드합니다. 호스트는 다음과 같은 앱의 리소스를 모두 캡슐화합니다.

  • HTTP 서버 구현
  • 미들웨어 구성 요소
  • 로깅
  • DI(종속성 주입) 서비스
  • 구성

ASP.NET Core 앱을 실행할 수 있는 세 가지 호스트가 있습니다.

ASP.NET Core WebApplication 및 WebApplicationBuilder 형식은 모든 ASP.NET Core 템플릿에서 권장되고 사용됩니다. WebApplication 는 .NET 제네릭 호스트와 유사하게 동작하며 많은 동일한 인터페이스를 노출하지만 구성하려면 콜백이 덜 필요합니다. ASP.NET Core WebHost 는 이전 버전과의 호환성을 위해서만 사용할 수 있습니다.

다음 예제에서는 다음을 인스턴스화합니다.WebApplication

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

WebApplicationBuilder.Build 메서드는 다음과 같은 일련의 기본 옵션으로 호스트를 구성합니다.

  • Kestrel을 웹 서버로 사용하고 IIS 통합을 사용하도록 설정합니다.
  • appsettings.json, 환경 변수, 명령줄 인수, 기타 구성 소스에서 구성을 로드합니다.
  • 콘솔 및 디버그 공급 기업에 로깅 출력을 보냅니다.

비 웹 시나리오

제네릭 호스트를 통해 다른 형식의 앱에서 로깅, DI(종속성 주입), 구성 및 앱 수명 관리와 같은 교차 프레임워크 확장을 사용할 수 있습니다. 자세한 내용은 ASP.NET Core의 .NET 제네릭 호스트 및 ASP.NET Core에서 호스트되는 서비스를 사용하는 백그라운드 작업을 참조하세요.

서버

ASP.NET Core 앱은 HTTP 요청을 수신하기 위해 HTTP 서버 구현을 사용합니다. 해당 서버는 HttpContext에 구성된 일련의 요청 기능으로 앱에 대한 요청을 표시합니다.

ASP.NET Core는 다음과 같은 서버 구현을 제공합니다.

  • Kestrel은 플랫폼 간 웹 서버입니다. Kestrel은 보통 IIS를 사용하여 역방향 프록시 구성에서 실행됩니다. ASP.NET Core 2.0 이상에서 Kestrel은 인터넷에 직접 노출되는 공용 에지 서버로 실행할 수 있습니다.
  • ‘IIS HTTP 서버’는 IIS를 사용하는 Windows용 서버입니다. 이 서버를 사용하면 ASP.NET Core 앱 및 IIS는 동일한 프로세스에서 실행됩니다.
  • HTTP.sys는 IIS에서 사용되지 않는 Windows용 서버입니다.

자세한 내용은 ASP.NET Core의 웹 서버 구현을 참조하세요.

구성

ASP.NET Core는 순서가 지정된 일련의 구성 공급자에서 이름-값 쌍으로 설정을 가져오는 구성 프레임워크를 제공합니다. 기본 제공 구성 공급자는 파일, 파일, .xml 환경 변수 및 명령줄 인수와 같은 .json 다양한 원본에 사용할 수 있습니다. 다른 소스를 지원하려면 사용자 지정 구성 공급자를 작성하세요.

기본적으로 ASP.NET Core 앱은 appsettings.json, 환경 변수, 명령줄 등에서 읽도록 구성되어 있습니다. 앱의 구성이 로드되면 환경 변수의 값이 appsettings.json의 값을 재정의합니다.

.NET Core는 암호와 같은 기밀 구성 데이터의 관리를 위해 비밀 관리자를 제공합니다. 프로덕션 비밀의 경우 Azure Key Vault를 사용하는 것이 좋습니다.

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

환경

Development, Staging 및 Production 같은 실행 환경을 ASP.NET Core에서 사용할 수 있습니다. ASPNETCORE_ENVIRONMENT 환경 변수를 설정하여 앱을 실행 중인 환경을 지정합니다. ASP.NET Core는 앱 시작 시 해당 환경 변수를 읽고 IWebHostEnvironment 구현에서 값을 저장합니다. 이 구현은 DI(종속성 주입)를 통해 앱의 어디서나 사용할 수 있습니다.

다음 예제에서는 Development 환경에서 실행되지 않는 경우 예외 처리기 및 HTTP HSTS(Strict Transport Security Protocol) 미들웨어를 구성합니다.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

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

로깅

ASP.NET Core는 다양한 기본 제공 및 타사 로깅 공급자와 함께 작동하는 로깅 API를 지원합니다. 사용 가능한 공급자는 다음과 같습니다.

  • 콘솔
  • 디버그
  • Windows 이벤트 추적
  • Windows 이벤트 로그
  • TraceSource
  • Azure App Service
  • Azure Application Insights

로그를 만들려면 DI(종속성 주입)로부터 ILogger<TCategoryName> 서비스를 확인하고 LogInformation과 같은 로깅 메서드를 호출합니다. 예시:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

자세한 내용은 .NET Core 및 ASP.NET Core의 로깅을 참조하세요.

라우팅

경로는 처리기에 매핑되는 URL 패턴입니다. 처리기는 일반적으로 Razor Page, MVC 컨트롤러의 작업 메서드 또는 미들웨어와 같습니다. ASP.NET Core 라우팅을 사용하면 앱에서 사용되는 URL을 제어할 수 있습니다.

ASP.NET Core 웹 애플리케이션 템플릿으로 생성되는 다음 코드는 UseRouting을 호출합니다.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

자세한 내용은 ASP.NET Core의 라우팅을 참조하세요.

오류 처리

ASP.NET Core에는 다음과 같은 오류를 처리하기 위한 기본 제공 기능이 포함됩니다.

  • 개발자 예외 페이지
  • 사용자 지정 오류 페이지
  • 정적 상태 코드 페이지
  • 시작 예외 처리

자세한 내용은 ASP.NET Core의 오류 처리를 참조하세요.

HTTP 요청하기

HttpClient 인스턴스를 만들기 위해 IHttpClientFactory를 구현할 수 있습니다. 팩터리는 다음과 같습니다.

  • 논리적 HttpClient 인스턴스를 구성하고 이름을 지정하기 위한 중앙 위치를 제공합니다. 예를 들어, GitHub에 액세스하는 github 클라이언트를 등록 및 구성합니다. 다른 용도를 위한 기본 클라이언트를 등록 및 구성합니다.
  • 나가는 요청 미들웨어 파이프라인을 빌드하기 위해 여러 위임 처리기를 연결하고 등록하도록 지원합니다. 이 패턴은 ASP.NET Core의 인바운드 미들웨어 파이프라인과 비슷합니다. 이 패턴은 캐싱, 오류 처리, serialization 및 로깅을 포함한 HTTP 요청 관련 횡단 문제를 관리하기 위한 메커니즘을 제공합니다.
  • 일시적인 오류를 처리하기 위해 널리 사용되는 타사 라이브러리인 Polly와 통합합니다.
  • HttpClient 수명을 수동으로 관리할 때 발생하는 일반적인 DNS 문제를 피하기 위해 기본 HttpClientHandler 인스턴스의 풀링 및 수명을 관리합니다.
  • 팩터리에서 만든 클라이언트를 통해 전송된 모든 요청에 대해 ILogger를 통해 구성 가능한 로깅 환경을 추가합니다.

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

콘텐츠 루트

콘텐츠 루트는 다음의 기본 경로입니다.

  • 앱을 호스트하는 실행 파일(.exe)
  • 앱을 구성하는 컴파일된 어셈블리(.dll)
  • 앱에서 사용하는 콘텐츠 파일은 다음과 같습니다.
    • Razor 파일(.cshtml, .razor)
    • 구성 파일(.json, .xml)
    • 데이터 파일(.db)
  • 웹 루트(일반적으로 wwwroot 폴더)

개발 중에는 콘텐츠 루트가 기본적으로 프로젝트의 루트 디렉터리로 설정됩니다. 이 디렉터리는 앱의 콘텐츠 파일과 웹 루트의 기본 경로이기도 합니다. 호스트를 빌드할 때는 경로를 설정하여 다른 콘텐츠 루트를 지정하세요. 자세한 내용은 콘텐츠 루트를 참조하세요.

웹 루트

웹 루트는 다음과 같은 퍼블릭 정적 리소스 파일의 기본 경로입니다.

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

정적 파일은 기본적으로 웹 루트 디렉터리와 그 하위 디렉터리에서만 제공됩니다. 웹 루트 경로는 기본적으로 {content root}/wwwroot로 설정됩니다. 호스트를 빌드할 때는 경로를 설정하여 다른 웹 루트를 지정하세요. 자세한 내용은 웹 루트를 참조하세요.

프로젝트 파일에서 <콘텐츠>프로젝트 항목을 사용하여 wwwroot에 파일을 게시하지 못하도록 합니다. 다음 예제에서는 wwwroot/local과 그 하위 디렉터리에서 콘텐츠가 게시되지 못하도록 합니다.

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

Razor.cshtml 파일에서는 ~/가 웹 루트를 가리킵니다. ~/(으)로 시작하는 경로를 가상 경로라고 합니다.

자세한 내용은 ASP.NET Core의 정적 파일을 참조하세요.

추가 리소스

이 문서에서는 DI(종속성 주입), 구성, 미들웨어 등을 포함하여 ASP.NET Core 앱을 빌드하기 위한 기본 사항의 개요를 간략하게 설명합니다.

Program.cs

웹 템플릿으로 만든 ASP.NET Core 앱은 Program.cs 파일에 애플리케이션 시작 코드를 포함합니다. Program.cs 파일은 다음과 같습니다.

  • 앱에서 요구하는 서비스가 구성됩니다.
  • 앱의 요청 처리 파이프라인이 일련의 미들웨어 구성 요소로 정의됩니다.

다음 앱 시작 코드는 다음을 지원합니다.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

종속성 주입(서비스)

ASP.NET Core에는 구성된 서비스를 앱을 통해 사용할 수 있도록 만드는 DI(종속성 주입) 프레임워크가 포함됩니다. 서비스는 위의 코드에서 WebApplicationBuilder.Services, builder.Services를 사용하여 DI 컨테이너에 추가됩니다. WebApplicationBuilder가 인스턴스화되면 프레임워크에서 제공하는 서비스가 다수 추가됩니다. builder는 아래 코드에서 WebApplicationBuilder입니다.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

위의 강조 표시된 코드에서 builder에는 구성, 로깅, 그리고 DI 컨테이너에 추가된 다른 많은 서비스가 있습니다.

다음 코드는 Razor Pages, 뷰가 있는 MVC 컨트롤러 및 사용자 지정 DbContext를 DI 컨테이너에 추가합니다.

using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Data;
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

builder.Services.AddDbContext<RazorPagesMovieContext>(options =>
   options.UseSqlServer(builder.Configuration.GetConnectionString("RPMovieContext")));

var app = builder.Build();

서비스는 일반적으로 DI로부터 생성자 주입을 사용하여 확인됩니다. DI 프레임워크가 런타임에 이 서비스의 인스턴스를 제공합니다.

다음 코드는 생성자 주입을 사용하여 DI에서 데이터베이스 컨텍스트 및 로거를 확인합니다.

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

미들웨어

요청 처리 파이프라인은 일련의 미들웨어 구성 요소로 구성됩니다. 각 구성 요소는 HttpContext에 대해 작업을 수행한 후 파이프라인에 있는 다음 미들웨어를 호출하거나 요청을 종료합니다.

규칙에 따라 미들웨어 구성 요소는 Use{Feature} 확장 메서드를 호출하여 파이프라인에 추가됩니다. 앱에 추가된 미들웨어가 다음 코드에서 강조 표시되어 있습니다.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

자세한 내용은 ASP.NET Core 미들웨어를 참조하세요.

호스트

ASP.NET Core 앱은 시작 시 ‘호스트’를 빌드합니다. 호스트는 다음과 같은 앱의 리소스를 모두 캡슐화합니다.

  • HTTP 서버 구현
  • 미들웨어 구성 요소
  • 로깅
  • DI(종속성 주입) 서비스
  • 구성

ASP.NET Core 앱을 실행할 수 있는 세 가지 호스트가 있습니다.

ASP.NET Core WebApplication 및 WebApplicationBuilder 형식은 모든 ASP.NET Core 템플릿에서 권장되고 사용됩니다. WebApplication 는 .NET 제네릭 호스트와 유사하게 동작하며 많은 동일한 인터페이스를 노출하지만 구성하려면 콜백이 덜 필요합니다. ASP.NET Core WebHost 는 이전 버전과의 호환성을 위해서만 사용할 수 있습니다.

다음 예제에서는 다음을 인스턴스화합니다.WebApplication

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

WebApplicationBuilder.Build 메서드는 다음과 같은 일련의 기본 옵션으로 호스트를 구성합니다.

  • Kestrel을 웹 서버로 사용하고 IIS 통합을 사용하도록 설정합니다.
  • appsettings.json, 환경 변수, 명령줄 인수, 기타 구성 소스에서 구성을 로드합니다.
  • 콘솔 및 디버그 공급 기업에 로깅 출력을 보냅니다.

비 웹 시나리오

제네릭 호스트를 통해 다른 형식의 앱에서 로깅, DI(종속성 주입), 구성 및 앱 수명 관리와 같은 교차 프레임워크 확장을 사용할 수 있습니다. 자세한 내용은 ASP.NET Core의 .NET 제네릭 호스트 및 ASP.NET Core에서 호스트되는 서비스를 사용하는 백그라운드 작업을 참조하세요.

서버

ASP.NET Core 앱은 HTTP 요청을 수신하기 위해 HTTP 서버 구현을 사용합니다. 해당 서버는 HttpContext에 구성된 일련의 요청 기능으로 앱에 대한 요청을 표시합니다.

ASP.NET Core는 다음과 같은 서버 구현을 제공합니다.

  • Kestrel은 플랫폼 간 웹 서버입니다. Kestrel은 보통 IIS를 사용하여 역방향 프록시 구성에서 실행됩니다. ASP.NET Core 2.0 이상에서 Kestrel은 인터넷에 직접 노출되는 공용 에지 서버로 실행할 수 있습니다.
  • ‘IIS HTTP 서버’는 IIS를 사용하는 Windows용 서버입니다. 이 서버를 사용하면 ASP.NET Core 앱 및 IIS는 동일한 프로세스에서 실행됩니다.
  • HTTP.sys는 IIS에서 사용되지 않는 Windows용 서버입니다.

자세한 내용은 ASP.NET Core의 웹 서버 구현을 참조하세요.

구성

ASP.NET Core는 순서가 지정된 일련의 구성 공급자에서 이름-값 쌍으로 설정을 가져오는 구성 프레임워크를 제공합니다. 기본 제공 구성 공급자는 파일, 파일, .xml 환경 변수 및 명령줄 인수와 같은 .json 다양한 원본에 사용할 수 있습니다. 다른 소스를 지원하려면 사용자 지정 구성 공급자를 작성하세요.

기본적으로 ASP.NET Core 앱은 appsettings.json, 환경 변수, 명령줄 등에서 읽도록 구성되어 있습니다. 앱의 구성이 로드되면 환경 변수의 값이 appsettings.json의 값을 재정의합니다.

.NET Core는 암호와 같은 기밀 구성 데이터의 관리를 위해 비밀 관리자를 제공합니다. 프로덕션 비밀의 경우 Azure Key Vault를 사용하는 것이 좋습니다.

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

환경

Development, Staging 및 Production 같은 실행 환경을 ASP.NET Core에서 사용할 수 있습니다. ASPNETCORE_ENVIRONMENT 환경 변수를 설정하여 앱을 실행 중인 환경을 지정합니다. ASP.NET Core는 앱 시작 시 해당 환경 변수를 읽고 IWebHostEnvironment 구현에서 값을 저장합니다. 이 구현은 DI(종속성 주입)를 통해 앱의 어디서나 사용할 수 있습니다.

다음 예제에서는 Development 환경에서 실행되지 않는 경우 예외 처리기 및 HTTP HSTS(Strict Transport Security Protocol) 미들웨어를 구성합니다.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseAuthorization();

app.MapGet("/hi", () => "Hello!");

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

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

로깅

ASP.NET Core는 다양한 기본 제공 및 타사 로깅 공급자와 함께 작동하는 로깅 API를 지원합니다. 사용 가능한 공급자는 다음과 같습니다.

  • 콘솔
  • 디버그
  • Windows 이벤트 추적
  • Windows 이벤트 로그
  • TraceSource
  • Azure App Service
  • Azure Application Insights

로그를 만들려면 DI(종속성 주입)로부터 ILogger<TCategoryName> 서비스를 확인하고 LogInformation과 같은 로깅 메서드를 호출합니다. 예시:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

자세한 내용은 .NET Core 및 ASP.NET Core의 로깅을 참조하세요.

라우팅

경로는 처리기에 매핑되는 URL 패턴입니다. 처리기는 일반적으로 Razor Page, MVC 컨트롤러의 작업 메서드 또는 미들웨어와 같습니다. ASP.NET Core 라우팅을 사용하면 앱에서 사용되는 URL을 제어할 수 있습니다.

ASP.NET Core 웹 애플리케이션 템플릿으로 생성되는 다음 코드는 UseRouting을 호출합니다.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

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

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

자세한 내용은 ASP.NET Core의 라우팅을 참조하세요.

오류 처리

ASP.NET Core에는 다음과 같은 오류를 처리하기 위한 기본 제공 기능이 포함됩니다.

  • 개발자 예외 페이지
  • 사용자 지정 오류 페이지
  • 정적 상태 코드 페이지
  • 시작 예외 처리

자세한 내용은 ASP.NET Core의 오류 처리를 참조하세요.

HTTP 요청하기

HttpClient 인스턴스를 만들기 위해 IHttpClientFactory를 구현할 수 있습니다. 팩터리는 다음과 같습니다.

  • 논리적 HttpClient 인스턴스를 구성하고 이름을 지정하기 위한 중앙 위치를 제공합니다. 예를 들어, GitHub에 액세스하는 github 클라이언트를 등록 및 구성합니다. 다른 용도를 위한 기본 클라이언트를 등록 및 구성합니다.
  • 나가는 요청 미들웨어 파이프라인을 빌드하기 위해 여러 위임 처리기를 연결하고 등록하도록 지원합니다. 이 패턴은 ASP.NET Core의 인바운드 미들웨어 파이프라인과 비슷합니다. 이 패턴은 캐싱, 오류 처리, serialization 및 로깅을 포함한 HTTP 요청 관련 횡단 문제를 관리하기 위한 메커니즘을 제공합니다.
  • 일시적인 오류를 처리하기 위해 널리 사용되는 타사 라이브러리인 Polly와 통합합니다.
  • HttpClient 수명을 수동으로 관리할 때 발생하는 일반적인 DNS 문제를 피하기 위해 기본 HttpClientHandler 인스턴스의 풀링 및 수명을 관리합니다.
  • 팩터리에서 만든 클라이언트를 통해 전송된 모든 요청에 대해 ILogger를 통해 구성 가능한 로깅 환경을 추가합니다.

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

콘텐츠 루트

콘텐츠 루트는 다음의 기본 경로입니다.

  • 앱을 호스트하는 실행 파일(.exe)
  • 앱을 구성하는 컴파일된 어셈블리(.dll)
  • 앱에서 사용하는 콘텐츠 파일은 다음과 같습니다.
    • Razor 파일(.cshtml, .razor)
    • 구성 파일(.json, .xml)
    • 데이터 파일(.db)
  • 웹 루트(일반적으로 wwwroot 폴더)

개발 중에는 콘텐츠 루트가 기본적으로 프로젝트의 루트 디렉터리로 설정됩니다. 이 디렉터리는 앱의 콘텐츠 파일과 웹 루트의 기본 경로이기도 합니다. 호스트를 빌드할 때는 경로를 설정하여 다른 콘텐츠 루트를 지정하세요. 자세한 내용은 콘텐츠 루트를 참조하세요.

웹 루트

웹 루트는 다음과 같은 퍼블릭 정적 리소스 파일의 기본 경로입니다.

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

정적 파일은 기본적으로 웹 루트 디렉터리와 그 하위 디렉터리에서만 제공됩니다. 웹 루트 경로는 기본적으로 {content root}/wwwroot로 설정됩니다. 호스트를 빌드할 때는 경로를 설정하여 다른 웹 루트를 지정하세요. 자세한 내용은 웹 루트를 참조하세요.

프로젝트 파일에서 <콘텐츠>프로젝트 항목을 사용하여 wwwroot에 파일을 게시하지 못하도록 합니다. 다음 예제에서는 wwwroot/local과 그 하위 디렉터리에서 콘텐츠가 게시되지 못하도록 합니다.

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

Razor.cshtml 파일에서는 ~/가 웹 루트를 가리킵니다. ~/(으)로 시작하는 경로를 가상 경로라고 합니다.

자세한 내용은 ASP.NET Core의 정적 파일을 참조하세요.

추가 리소스

이 문서에서는 DI(종속성 주입), 구성, 미들웨어 등을 포함하여 ASP.NET Core 앱을 빌드하기 위한 기본 사항의 개요를 간략하게 설명합니다.

시작 클래스

Startup 클래스에서는 다음을 수행합니다.

  • 앱에서 요구하는 서비스가 구성됩니다.
  • 앱의 요청 처리 파이프라인이 일련의 미들웨어 구성 요소로 정의됩니다.

샘플 Startup 클래스는 다음과 같습니다.

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에서 앱 시작을 참조하세요.

종속성 주입(서비스)

ASP.NET Core는 구성된 서비스를 앱을 통해 사용할 수 있도록 만드는 기본 제공 DI(종속성 주입) 프레임워크를 포함합니다. 예를 들어 로깅 구성 요소는 서비스입니다.

서비스를 구성(또는 등록)하는 코드는 Startup.ConfigureServices 메서드에 추가됩니다. 예시:

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

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

서비스는 일반적으로 DI로부터 생성자 주입을 사용하여 확인됩니다. 생성자 주입에서는 클래스가 필요한 형식 또는 인터페이스의 생성자 매개 변수를 선언합니다. DI 프레임워크가 런타임에 이 서비스의 인스턴스를 제공합니다.

다음 예제에서는 생성자 주입을 사용하여 DI로부터 RazorPagesMovieContext를 확인합니다.

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 컨테이너를 사용할 수 있습니다.

자세한 내용은 ASP.NET Core에서 종속성 주입을 참조하세요.

미들웨어

요청 처리 파이프라인은 일련의 미들웨어 구성 요소로 구성됩니다. 각 구성 요소는 HttpContext에 대해 작업을 수행한 후 파이프라인에 있는 다음 미들웨어를 호출하거나 요청을 종료합니다.

규칙에 따라 미들웨어 구성 요소는 Startup.Configure 메서드에서 Use... 확장 메서드를 호출하여 파이프라인에 추가됩니다. 예를 들어 정적 파일을 렌더링하도록 설정하려면 UseStaticFiles를 호출합니다.

다음 예제에서는 요청 처리 파이프라인을 구성합니다.

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

    app.UseRouting();

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

ASP.NET Core는 풍부한 일련의 기본 제공 미들웨어를 포함합니다. 사용자 지정 미들웨어 구성 요소를 작성할 수도 있습니다.

자세한 내용은 ASP.NET Core 미들웨어를 참조하세요.

호스트

ASP.NET Core 앱은 시작 시 ‘호스트’를 빌드합니다. 호스트는 다음과 같은 앱의 리소스를 모두 캡슐화합니다.

  • HTTP 서버 구현
  • 미들웨어 구성 요소
  • 로깅
  • DI(종속성 주입) 서비스
  • 구성

호스트에는 다음 두 가지가 있습니다.

  • .NET 일반 호스트
  • ASP.NET Core 웹 호스트

.NET 일반 호스트를 사용하는 것이 좋습니다. ASP.NET Core 웹 호스트는 이전 버전과의 호환성을 위해서만 제공됩니다.

다음 예제에서는 .NET 일반 호스트를 만듭니다.

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

CreateDefaultBuilder 및 ConfigureWebHostDefaults 메서드는 다음과 같은 기본 옵션으로 호스트를 구성합니다.

  • Kestrel을 웹 서버로 사용하고 IIS 통합을 사용하도록 설정합니다.
  • appsettings.json, appsettings.{Environment}.json, 환경 변수, 명령줄 인수, 기타 구성 소스에서 구성을 로드합니다.
  • 콘솔 및 디버그 공급 기업에 로깅 출력을 보냅니다.

자세한 내용은 ASP.NET Core의 .NET 제네릭 호스트를 참조하세요.

비 웹 시나리오

제네릭 호스트를 통해 다른 형식의 앱에서 로깅, DI(종속성 주입), 구성 및 앱 수명 관리와 같은 교차 프레임워크 확장을 사용할 수 있습니다. 자세한 내용은 ASP.NET Core의 .NET 제네릭 호스트 및 ASP.NET Core에서 호스트되는 서비스를 사용하는 백그라운드 작업을 참조하세요.

서버

ASP.NET Core 앱은 HTTP 요청을 수신하기 위해 HTTP 서버 구현을 사용합니다. 해당 서버는 HttpContext에 구성된 일련의 요청 기능으로 앱에 대한 요청을 표시합니다.

ASP.NET Core는 다음과 같은 서버 구현을 제공합니다.

  • Kestrel은 플랫폼 간 웹 서버입니다. Kestrel은 보통 IIS를 사용하여 역방향 프록시 구성에서 실행됩니다. ASP.NET Core 2.0 이상에서 Kestrel은 인터넷에 직접 노출되는 공용 에지 서버로 실행할 수 있습니다.
  • ‘IIS HTTP 서버’는 IIS를 사용하는 Windows용 서버입니다. 이 서버를 사용하면 ASP.NET Core 앱 및 IIS는 동일한 프로세스에서 실행됩니다.
  • HTTP.sys는 IIS에서 사용되지 않는 Windows용 서버입니다.

자세한 내용은 ASP.NET Core의 웹 서버 구현을 참조하세요.

구성

ASP.NET Core는 순서가 지정된 일련의 구성 공급자에서 이름-값 쌍으로 설정을 가져오는 구성 프레임워크를 제공합니다. 기본 제공 구성 공급자는 파일, 파일, .xml 환경 변수 및 명령줄 인수와 같은 .json 다양한 원본에 사용할 수 있습니다. 다른 소스를 지원하려면 사용자 지정 구성 공급자를 작성하세요.

기본적으로 ASP.NET Core 앱은 appsettings.json, 환경 변수, 명령줄 등에서 읽도록 구성되어 있습니다. 앱의 구성이 로드되면 환경 변수의 값이 appsettings.json의 값을 재정의합니다.

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

.NET Core는 암호와 같은 기밀 구성 데이터의 관리를 위해 비밀 관리자를 제공합니다. 프로덕션 비밀의 경우 Azure Key Vault를 사용하는 것이 좋습니다.

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

환경

Development, Staging 및 Production과 같은 실행 환경은 ASP.NET Core의 일급 개념입니다. ASPNETCORE_ENVIRONMENT 환경 변수를 설정하여 앱을 실행 중인 환경을 지정합니다. ASP.NET Core는 앱 시작 시 해당 환경 변수를 읽고 IWebHostEnvironment 구현에서 값을 저장합니다. 이 구현은 DI(종속성 주입)를 통해 앱의 어디서나 사용할 수 있습니다.

다음 예제에서는 앱이 Development 환경에서 실행될 때 상세한 오류 정보를 제공하도록 구성합니다.

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에서 여러 환경 사용을 참조하세요.

로깅

ASP.NET Core는 다양한 기본 제공 및 타사 로깅 공급자와 함께 작동하는 로깅 API를 지원합니다. 사용 가능한 공급자는 다음과 같습니다.

  • 콘솔
  • 디버그
  • Windows 이벤트 추적
  • Windows 이벤트 로그
  • TraceSource
  • Azure App Service
  • Azure Application Insights

로그를 만들려면 DI(종속성 주입)로부터 ILogger<TCategoryName> 서비스를 확인하고 LogInformation과 같은 로깅 메서드를 호출합니다. 예시:

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과 같은 로깅 메서드는 임의 개수의 필드를 지원합니다. 필드는 일반적으로 메시지 string을 생성하는 데 사용되지만 일부 로깅 공급자는 이들 필드를 별도의 필드로 데이터 저장소로 보냅니다. 이 기능을 사용하면 로그 공급 기업이 구조적 로깅이라고도 하는 의미 체계 로깅을 구현할 수 있게 됩니다.

자세한 내용은 .NET Core 및 ASP.NET Core의 로깅을 참조하세요.

라우팅

경로는 처리기에 매핑되는 URL 패턴입니다. 처리기는 일반적으로 Razor Page, MVC 컨트롤러의 작업 메서드 또는 미들웨어와 같습니다. ASP.NET Core 라우팅을 사용하면 앱에서 사용되는 URL을 제어할 수 있습니다.

자세한 내용은 ASP.NET Core의 라우팅을 참조하세요.

오류 처리

ASP.NET Core에는 다음과 같은 오류를 처리하기 위한 기본 제공 기능이 포함됩니다.

  • 개발자 예외 페이지
  • 사용자 지정 오류 페이지
  • 정적 상태 코드 페이지
  • 시작 예외 처리

자세한 내용은 ASP.NET Core의 오류 처리를 참조하세요.

HTTP 요청하기

HttpClient 인스턴스를 만들기 위해 IHttpClientFactory를 구현할 수 있습니다. 팩터리는 다음과 같습니다.

  • 논리적 HttpClient 인스턴스를 구성하고 이름을 지정하기 위한 중앙 위치를 제공합니다. 예를 들어, GitHub에 액세스하는 github 클라이언트를 등록 및 구성합니다. 다른 용도를 위한 기본 클라이언트를 등록 및 구성합니다.
  • 나가는 요청 미들웨어 파이프라인을 빌드하기 위해 여러 위임 처리기를 연결하고 등록하도록 지원합니다. 이 패턴은 ASP.NET Core의 인바운드 미들웨어 파이프라인과 비슷합니다. 이 패턴은 캐싱, 오류 처리, serialization 및 로깅을 포함한 HTTP 요청 관련 횡단 문제를 관리하기 위한 메커니즘을 제공합니다.
  • 일시적인 오류를 처리하기 위해 널리 사용되는 타사 라이브러리인 Polly와 통합합니다.
  • HttpClient 수명을 수동으로 관리할 때 발생하는 일반적인 DNS 문제를 피하기 위해 기본 HttpClientHandler 인스턴스의 풀링 및 수명을 관리합니다.
  • 팩터리에서 만든 클라이언트를 통해 전송된 모든 요청에 대해 ILogger를 통해 구성 가능한 로깅 환경을 추가합니다.

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

콘텐츠 루트

콘텐츠 루트는 다음의 기본 경로입니다.

  • 앱을 호스트하는 실행 파일(.exe)
  • 앱을 구성하는 컴파일된 어셈블리(.dll)
  • 앱에서 사용하는 콘텐츠 파일은 다음과 같습니다.
    • Razor 파일(.cshtml, .razor)
    • 구성 파일(.json, .xml)
    • 데이터 파일(.db)
  • 웹 루트(일반적으로 wwwroot 폴더)

개발 중에는 콘텐츠 루트가 기본적으로 프로젝트의 루트 디렉터리로 설정됩니다. 이 디렉터리는 앱의 콘텐츠 파일과 웹 루트의 기본 경로이기도 합니다. 호스트를 빌드할 때는 경로를 설정하여 다른 콘텐츠 루트를 지정하세요. 자세한 내용은 콘텐츠 루트를 참조하세요.

웹 루트

웹 루트는 다음과 같은 퍼블릭 정적 리소스 파일의 기본 경로입니다.

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

정적 파일은 기본적으로 웹 루트 디렉터리와 그 하위 디렉터리에서만 제공됩니다. 웹 루트 경로는 기본적으로 {content root}/wwwroot로 설정됩니다. 호스트를 빌드할 때는 경로를 설정하여 다른 웹 루트를 지정하세요. 자세한 내용은 웹 루트를 참조하세요.

프로젝트 파일에서 <콘텐츠>프로젝트 항목을 사용하여 wwwroot에 파일을 게시하지 못하도록 합니다. 다음 예제에서는 wwwroot/local과 그 하위 디렉터리에서 콘텐츠가 게시되지 못하도록 합니다.

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

Razor.cshtml 파일에서는 물결표-슬래시(~/)가 웹 루트를 가리킵니다. ~/(으)로 시작하는 경로를 가상 경로라고 합니다.

자세한 내용은 ASP.NET Core의 정적 파일을 참조하세요.