共用方式為


ASP.NET Core 基本概念的概觀

注意

這不是這篇文章的最新版本。 如需目前的版本,請參閱 本文的 .NET 9 版本。

警告

不再支援此版本的 ASP.NET Core。 如需詳細資訊,請參閱 .NET 和 .NET Core 支持原則。 如需目前的版本,請參閱 本文的 .NET 9 版本。

重要

這些發行前產品的相關資訊在產品正式發行前可能會有大幅修改。 Microsoft 對此處提供的資訊,不做任何明確或隱含的瑕疵擔保。

如需目前的版本,請參閱 本文的 .NET 9 版本。

本文提供建置 ASP.NET Core 應用程式的基本概念概觀,包括相依性插入 (DI)、設定、中介軟體等等。

如需 Blazor 基本概念指引,這會新增或取代本文中的指導方針,請參閱 ASP.NET Core Blazor 基本概念

Program.cs

使用 Web 範本建立的 ASP.NET Core 應用程式包含 Program.cs 檔案中的應用程式啟動程式碼。 Program.cs 檔案位於下列位置:

  • 已設定應用程式所需的服務。
  • 應用程式的要求處理管線是定義為一系列中介軟體元件

下列應用程式啟動程式代碼支援數種應用程式類型:

using WebAll.Components;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();
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.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.UseAntiforgery();

app.Run();

相依性插入 (服務)

ASP.NET Core 功能內建的 相依注入 (DI),讓設定好的服務能在整個應用程式中使用。 在上述程式碼中,服務會新增至具有 WebApplicationBuilder.Servicesbuilder.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();

在上述程式代碼中,CreateBuilder 將設定、記錄和 許多其他服務 至 DI 容器。 DI 架構會在運行時間提供要求服務的實例。

下列程式代碼會將自訂 DbContext 和 Blazor 元件新增至 DI 容器:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContextFactory<BlazorWebAppMoviesContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("MoviesContext") 
        ?? throw new InvalidOperationException("Connection string not found.")));

builder.Services.AddQuickGridEntityFrameworkAdapter();

builder.Services.AddDatabaseDeveloperPageExceptionFilter();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();

在 Blazor Web App中,服務通常會在執行時從 DI 解析,方法是在 Razor 元件中使用 @inject 指令,如下列範例所示:

@page "/movies"
@rendermode InteractiveServer
@using Microsoft.EntityFrameworkCore
@using Microsoft.AspNetCore.Components.QuickGrid
@using BlazorWebAppMovies.Models
@using BlazorWebAppMovies.Data
@implements IAsyncDisposable
@inject IDbContextFactory<BlazorWebAppMovies.Data.BlazorWebAppMoviesContext> DbFactory

<PageTitle>Index</PageTitle>

<h1>Index</h1>

<div>
    <input type="search" @bind="titleFilter" @bind:event="oninput" />
</div>

<p>
    <a href="movies/create">Create New</a>
</p>

<QuickGrid Class="table" Items="FilteredMovies" Pagination="pagination">
    <PropertyColumn Property="movie => movie.Title" Sortable="true" />
    <PropertyColumn Property="movie => movie.ReleaseDate" Title="Release Date" />
    <PropertyColumn Property="movie => movie.Genre" />
    <PropertyColumn Property="movie => movie.Price" />
    <PropertyColumn Property="movie => movie.Rating" />

    <TemplateColumn Context="movie">
        <a href="@($"movies/edit?id={movie.Id}")">Edit</a> |
        <a href="@($"movies/details?id={movie.Id}")">Details</a> |
        <a href="@($"movies/delete?id={movie.Id}")">Delete</a>
    </TemplateColumn>
</QuickGrid>

<Paginator State="pagination" />

@code {
    private BlazorWebAppMoviesContext context = default!;
    private PaginationState pagination = new PaginationState { ItemsPerPage = 10 };
    private string titleFilter = string.Empty;

    private IQueryable<Movie> FilteredMovies =>
        context.Movie.Where(m => m.Title!.Contains(titleFilter));

    protected override void OnInitialized()
    {
        context = DbFactory.CreateDbContext();
    }

    public async ValueTask DisposeAsync() => await context.DisposeAsync();
}

在上述程式代碼中:

  • 使用 @inject 指示詞。
  • 服務會在 OnInitialized 方法中解析,並指派給 context 變數。
  • context 服務創建 FilteredMovie 清單。

另一種從 DI 解析服務的方法是透過建構子注入。 下列 Razor Pages 程式代碼會使用建構函式插入解析資料庫內容和 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();
    }
}

在上述程式代碼中,IndexModel 建構函式會採用類型為 RazorPagesMovieContext的參數,其會在運行時間解析為 _context 變數。 內容物件可用來在 OnGetAsync 方法中建立電影清單。

如需詳細資訊,請參閱 ASP.NET Core Blazor 相依性注入ASP.NET Core中的相依性注入。

中介軟體

要求處理管線由一系列中介軟體元件所組成。 每個元件會在 HttpContext 上執行操作,並叫用管線中下一個中介軟體或終止要求。

依照慣例,中介軟體元件會透過叫用 Use{Feature} 延伸模組方法來新增至管線。 下列程式代碼說明如何使用名為 Use{Feature} 的方法,將中間件新增至應用程式:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContextFactory<BlazorWebAppMoviesContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("MoviesContext") 
        ?? throw new InvalidOperationException("Connection string not found.")));

builder.Services.AddQuickGridEntityFrameworkAdapter();

builder.Services.AddDatabaseDeveloperPageExceptionFilter();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();

using (var scope = app.Services.CreateScope())
{
    var services = scope.ServiceProvider;

    SeedData.Initialize(services);
}

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
    app.UseMigrationsEndPoint();
}
app.UseHttpsRedirection();

app.UseAntiforgery();

app.MapStaticAssets();
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.Run();

如需詳細資訊,請參閱 ASP.NET Core 中介軟體

Host

在啟動時,ASP.NET Core 應用程式會建置一個「主機」。 主機會封裝所有應用程式的資源,例如:

  • HTTP 伺服器實作
  • 中介軟體元件
  • 記錄
  • 相依性插入 (服務)
  • 組態

有三個不同的主機能夠執行 ASP.NET Core 應用程式:

建議使用 ASP.NET Core WebApplicationWebApplicationBuilder 類型,並用於所有 ASP.NET Core 範本中。 WebApplication 的行為類似於 .NET 泛型主機,並公開許多相同的介面,但需要較少的回呼才能設定。 ASP.NET Core WebHost 僅適用於回溯相容性。

下列範例會具現化 WebApplication,並將它指派給名為 app的變數:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContextFactory<BlazorWebAppMoviesContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("MoviesContext") 
        ?? throw new InvalidOperationException("Connection string not found.")));

builder.Services.AddQuickGridEntityFrameworkAdapter();

builder.Services.AddDatabaseDeveloperPageExceptionFilter();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();

WebApplicationBuilder.Build 方法會使用一組預設選項來設定主機,例如:

  • 使用 Kestrel 做為網頁伺服器,並啟用 IIS 整合。
  • 、環境變數、命令列引數及其他來源載入appsettings.json
  • 將記錄輸出傳送到主控台及偵錯提供者。

非 Web 案例

一般主機可讓其他類型的應用程式使用跨領域架構延伸模組,例如記錄、相依性插入 (DI)、組態和應用程式存留期管理。 如需詳細資訊,請參閱 ASP.NET Core 中的 .NET 泛型主機,以及在 ASP.NET Core 中使用託管服務的背景工作

伺服器

ASP.NET Core 應用程式使用 HTTP 伺服器實作來接聽 HTTP 要求。 伺服器會把向應用程式發出的要求作為一組要求功能,合併成一個 HttpContext

ASP.NET Core 隨附下列伺服器實作:

  • Kestrel 是跨平台的網頁伺服器。 Kestrel 通常會使用 IIS 在反向 Proxy 設定中執行。 在 ASP.NET Core 2.0 和更新版本中,Kestrel 可作為直接公開至因特網的公開邊緣伺服器來執行。
  • IIS HTTP 伺服器則是適用於使用 IIS Windows 的伺服器。 透過此伺服器,ASP.NET Core 應用程式及 IIS 便可以在相同處理序中執行。
  • HTTP.sys 則是適用於並未搭配 IIS 使用 Windows 的伺服器。

如需詳細資訊,請參閱在 ASP.NET Core 中實作網頁伺服器

組態

ASP.NET Core 提供組態架構,可從組態提供者的已排序集合中,以成對名稱和數值的形式取得設定。 您可以使用各種來源的內建組態提供者,例如 .json 檔案、.xml 檔案、環境變數及命令列引數。 撰寫自訂組態提供者以支援其他來源。

根據預設,ASP.NET Core 應用程式會設定為從 appsettings.json、環境變數、命令列等進行讀取。 載入應用程式的組態時,來自環境變數的值會覆寫來自 appsettings.json 的值。

為了在開發環境中管理機密設定數據,例如密碼,.NET Core 提供 Secret Manager。 針對生產祕密,我們建議使用 Azure Key Vault

如需詳細資訊,請參閱 ASP.NET Core 中的組態

環境

ASP.NET Core 中提供執行環境,例如 DevelopmentStagingProduction。 透過設定 ASPNETCORE_ENVIRONMENT 環境變數來指定應用程式執行的環境。 ASP.NET Core 會在應用程式啟動時讀取環境變數,然後將值儲存在 IWebHostEnvironment 實作中。 您可在應用程式中透過相依性插入 (DI) 取得此實作。

下列範例會在 環境中執行時,設定例外處理常式和 Development 中介軟體:

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
    app.UseMigrationsEndPoint();
}

如需詳細資訊,請參閱在 ASP.NET Core 中使用多個環境 (部分機器翻譯)。

記錄

ASP.NET Core 支援記錄 API,此 API 能與各種內建和第三方記錄提供者搭配使用。 可用的提供者包括:

  • 主控台
  • 偵錯
  • Windows 上的事件追蹤
  • Windows 事件記錄檔
  • TraceSource
  • Azure App Service
  • Azure Application Insights

若要建立記錄,ILogger<TCategoryName>請從相依性插入 (DI) 和通話記錄方法 (例如 LogInformation) 解析服務。 下列範例示範如何取得和使用 Blazor Web App中頁面 .razor 檔案中的記錄器。 當在 Program.cs中呼叫 CreateBuilder 方法時,記錄器物件及其控制台提供者會自動儲存在 DI 容器中。

@page "/weather"
@attribute [StreamRendering]
@inject ILogger<Weather> Logger

<PageTitle>Weather</PageTitle>

<h1>Weather</h1>

<p>This component demonstrates showing data and logging.</p>

@if (forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th aria-label="Temperature in Celsius">Temp. (C)</th>
                <th aria-label="Temperature in Farenheit">Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    private WeatherForecast[]? forecasts;

    protected override async Task OnInitializedAsync()
    {
        // Simulate asynchronous loading to demonstrate streaming rendering
       
        await Task.Delay(500);

        Logger.LogInformation("This is an information log message.");
        Logger.LogWarning("This is a warning log message.");
        Logger.LogError("This is an error log message.");

        var startDate = DateOnly.FromDateTime(DateTime.Now);
        var summaries = new[] { "Freezing", "Bracing", "Chilly",
            "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" };
        forecasts = Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = startDate.AddDays(index),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = summaries[Random.Shared.Next(summaries.Length)]
        }).ToArray();
    }

    private class WeatherForecast
    {
        public DateOnly Date { get; set; }
        public int TemperatureC { get; set; }
        public string? Summary { get; set; }
        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    }
}

如需詳細資料,請參閱 .NET Core 與 ASP.NET Core 中的記錄

路由

ASP.NET Core 中的路由是將連入要求對應至應用程式中特定端點的機制。 它可讓您定義對應至不同元件的 URL 模式,例如 Blazor 元件、Razor 頁面、MVC 控制器動作或中間件。

UseRouting(IApplicationBuilder) 方法會將路由中間件新增至要求管線。 此中間件會處理路由資訊,並判斷每個要求的適當端點。 除非您想要變更中間件處理的順序,否則您不需要明確呼叫 UseRouting

如需詳細資訊,請參閱 ASP.NET Core 和 ASP.NET Core 路由和瀏覽中的 路由。

錯誤處理

ASP.NET Core 具有處理錯誤的內建功能,例如:

  • 開發人員例外狀況頁面
  • 自訂錯誤頁面
  • 靜態狀態碼頁面
  • 啟動例外狀況處理

如需詳細資訊,請參閱處理 ASP.NET Core 中的錯誤

發出 HTTP 要求

IHttpClientFactory 的實作可用於建立 HttpClient 執行個體。 Factory:

  • 提供一個集中位置以便命名和設定邏輯 HttpClient 執行個體。 例如,註冊並設定 Github 用戶端以存取 GitHub。 註冊並設定預設用戶端以供其他用途使用。
  • 支援註冊及多個委派處理常式的鏈結,以用於建置傳出要求中介軟體管線。 此模式與 ASP.NET Core 的輸入中介軟體管線相似。 模式提供一個機制來管理 HTTP 要求的跨領域關注,包括快取、錯誤處理、序列化和記錄。
  • Polly 整合,Polly 是一種熱門的協力廠商程式庫,用於進行暫時性的錯誤處理。
  • 管理基礎 HttpClientHandler 執行個體的共用和存留期,以避免在手動管理 HttpClient 存留期時,發生的常見 DNS 問題。
  • 針對透過處理站所建立之用戶端傳送的所有要求,新增可設定的記錄體驗 (透過 ILogger)。

如需詳細資訊,請參閱在 ASP.NET Core 中使用 IHttpClientFactory 發出 HTTP 要求

內容根目錄

內容根目錄是下列項目的基底路徑:

  • 裝載應用程式的可執行檔 (.exe)。
  • 構成應用程式 (.dll) 的已編譯組件。
  • 應用程式使用的內容檔案,例如:
    • Razor 檔案 (.cshtml.razor)
    • 組態檔 (.json.xml)
    • 資料檔案 (.db)
  • Web 根目錄,通常是 wwwroot 資料夾。

在開發期間,內容根目錄預設為專案的根目錄。 此目錄也是應用程式內容檔案和 Web 根目錄的基底路徑。 指定不同的內容根目錄,方法是在建置主機時設定其路徑。 如需詳細資訊,請參閱內容根

Web 根目錄

Web 根目錄是公用靜態資源檔的基底路徑,例如:

  • 樣式表單 (.css)
  • JavaScript (.js)
  • 映像 (.png.jpg)

根據預設,靜態檔案只會處理來自 Web 根目錄及其子目錄的檔案。 Web 根路徑預設為 {content root}/wwwroot。 指定不同的 Web 根目錄,方法是在建置主機時設定其路徑。 如需詳細資訊,請參閱 Web 根目錄

防止在 wwwroot 中使用專案檔中的>來發佈檔案。 下列範例會防止在 wwwroot/local 及其子目錄中發佈內容:

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

在 Razor.cshtml 檔案中,~/ 會指向 Web 根目錄。 開頭為 ~/ 的路徑稱為虛擬路徑

如需詳細資訊,請參閱 ASP.NET Core 中的靜態檔案

其他資源

本文提供建置 ASP.NET Core 應用程式的基本概念概觀,包括相依性插入 (DI)、設定、中介軟體等等。

Program.cs

使用 Web 範本建立的 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.Servicesbuilder.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 中介軟體

Host

在啟動時,ASP.NET Core 應用程式會建置一個「主機」。 主機會封裝所有應用程式的資源,例如:

  • HTTP 伺服器實作
  • 中介軟體元件
  • 記錄
  • 相依性插入 (服務)
  • 組態

有三個不同的主機能夠執行 ASP.NET Core 應用程式:

建議使用 ASP.NET Core WebApplicationWebApplicationBuilder 類型,並用於所有 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
  • 將記錄輸出傳送到主控台及偵錯提供者。

非 Web 案例

一般主機允許其他類型的應用程式,使用交叉剪輯架構延伸模組,例如記錄、相依性插入 (DI)、設定與應用程式存留期管理。 如需詳細資訊,請參閱 ASP.NET Core 中的 .NET 泛型主機,以及在 ASP.NET Core 中使用託管服務的背景工作

伺服器

ASP.NET Core 應用程式使用 HTTP 伺服器實作來接聽 HTTP 要求。 伺服器會把向應用程式發出的要求作為一組要求功能,合併成一個 HttpContext

ASP.NET Core 隨附下列伺服器實作:

  • Kestrel 是跨平台的網頁伺服器。 Kestrel 通常會使用 IIS 在反向 Proxy 設定中執行。 在 ASP.NET Core 2.0 或更新版本中,Kestrel 可以做為直接向網際網路公開的公眾 Edge Server 執行。
  • IIS HTTP 伺服器則是適用於使用 IIS Windows 的伺服器。 透過此伺服器,ASP.NET Core 應用程式及 IIS 便可以在相同處理序中執行。
  • HTTP.sys 則是適用於並未搭配 IIS 使用 Windows 的伺服器。

如需詳細資訊,請參閱在 ASP.NET Core 中實作網頁伺服器

組態

ASP.NET Core 提供組態架構,可從組態提供者的已排序集合中,以成對名稱和數值的形式取得設定。 您可以使用各種來源的內建組態提供者,例如 .json 檔案、.xml 檔案、環境變數及命令列引數。 撰寫自訂組態提供者以支援其他來源。

根據預設,ASP.NET Core 應用程式會設定為從 appsettings.json、環境變數、命令列等進行讀取。 載入應用程式的組態時,來自環境變數的值會覆寫來自 appsettings.json 的值。

針對管理保密組態資料 (例如密碼),.NET Core 提供祕密管理員。 針對生產祕密,我們建議使用 Azure Key Vault

如需詳細資訊,請參閱 ASP.NET Core 中的組態

環境

ASP.NET Core 中提供執行環境,例如 DevelopmentStagingProduction。 透過設定 ASPNETCORE_ENVIRONMENT 環境變數來指定應用程式執行的環境。 ASP.NET Core 會在應用程式啟動時讀取環境變數,然後將值儲存在 IWebHostEnvironment 實作中。 您可在應用程式中透過相依性插入 (DI) 取得此實作。

下列範例會在 環境中執行時,設定例外處理常式和 Development 中介軟體:

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,此 API 能與各種內建和第三方記錄提供者搭配使用。 可用的提供者包括:

  • 主控台
  • 偵錯
  • Windows 上的事件追蹤
  • Windows 事件記錄檔
  • TraceSource
  • Azure App Service
  • Azure Application Insights

若要建立記錄,ILogger<TCategoryName>請從相依性插入 (DI) 和通話記錄方法 (例如 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 頁面、MVC 控制器中的動作方法,或是中介軟體。 ASP.NET Core 路由可讓您控制您應用程式使用的 URL。

ASP.NET Core Web 應用程式範本所產生的下列程式碼會呼叫 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 要求

IHttpClientFactory 的實作可用於建立 HttpClient 執行個體。 Factory:

  • 提供一個集中位置以便命名和設定邏輯 HttpClient 執行個體。 例如,註冊並設定 Github 用戶端以存取 GitHub。 註冊並設定預設用戶端以供其他用途使用。
  • 支援註冊及多個委派處理常式的鏈結,以用於建置傳出要求中介軟體管線。 此模式與 ASP.NET Core 的輸入中介軟體管線相似。 模式提供一個機制來管理 HTTP 要求的跨領域關注,包括快取、錯誤處理、序列化和記錄。
  • Polly 整合,Polly 是一種熱門的協力廠商程式庫,用於進行暫時性的錯誤處理。
  • 管理基礎 HttpClientHandler 執行個體的共用和存留期,以避免在手動管理 HttpClient 存留期時,發生的常見 DNS 問題。
  • 針對透過處理站所建立之用戶端傳送的所有要求,新增可設定的記錄體驗 (透過 ILogger)。

如需詳細資訊,請參閱在 ASP.NET Core 中使用 IHttpClientFactory 發出 HTTP 要求

內容根目錄

內容根目錄是下列項目的基底路徑:

  • 裝載應用程式的可執行檔 (.exe)。
  • 構成應用程式 (.dll) 的已編譯組件。
  • 應用程式使用的內容檔案,例如:
    • Razor 檔案 (.cshtml.razor)
    • 組態檔 (.json.xml)
    • 資料檔案 (.db)
  • Web 根目錄,通常是 wwwroot 資料夾。

在開發期間,內容根目錄預設為專案的根目錄。 此目錄也是應用程式內容檔案和 Web 根目錄的基底路徑。 指定不同的內容根目錄,方法是在建置主機時設定其路徑。 如需詳細資訊,請參閱內容根

Web 根目錄

Web 根目錄是公用靜態資源檔的基底路徑,例如:

  • 樣式表單 (.css)
  • JavaScript (.js)
  • 映像 (.png.jpg)

根據預設,靜態檔案只會處理來自 Web 根目錄及其子目錄的檔案。 Web 根路徑預設為 {content root}/wwwroot。 指定不同的 Web 根目錄,方法是在建置主機時設定其路徑。 如需詳細資訊,請參閱 Web 根目錄

防止在 wwwroot 中使用專案檔中的>來發佈檔案。 下列範例會防止在 wwwroot/local 及其子目錄中發佈內容:

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

在 Razor.cshtml 檔案中,~/ 會指向 Web 根目錄。 開頭為 ~/ 的路徑稱為虛擬路徑

如需詳細資訊,請參閱 ASP.NET Core 中的靜態檔案

其他資源

本文提供建置 ASP.NET Core 應用程式的基本概念概觀,包括相依性插入 (DI)、設定、中介軟體等等。

Startup 類別

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) 容器不符合應用程式的所有需求,則可以改用協力廠商 IoC 容器。

如需詳細資訊,請參閱在 ASP.NET Core 中插入相依性

中介軟體

要求處理管線由一系列中介軟體元件所組成。 每個元件會在 HttpContext 上執行操作,並叫用管線中下一個中介軟體或終止要求。

依照慣例,中介軟體元件會透過叫用 Use... 方法中的 Startup.Configure 延伸模組方法來新增至管線。 例如,若要啟用靜態檔案轉譯,請呼叫 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 中介軟體

Host

在啟動時,ASP.NET Core 應用程式會建置一個「主機」。 主機會封裝所有應用程式的資源,例如:

  • HTTP 伺服器實作
  • 中介軟體元件
  • 記錄
  • 相依性插入 (服務)
  • 組態

有兩個不同的主機:

  • .NET 泛型主機
  • ASP.NET Core Web 主機

建議使用 .NET 泛型主機。 ASP.NET Core Web 主機僅適用於回溯相容性。

下列範例會建立 .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>();
            });
}

CreateDefaultBuilderConfigureWebHostDefaults 方法會使用一組預設選項來設定主機,例如:

  • 使用 Kestrel 做為網頁伺服器,並啟用 IIS 整合。
  • appsettings.jsonappsettings.{Environment}.json、環境變數、命令列引數及其他來源載入組態。
  • 將記錄輸出傳送到主控台及偵錯提供者。

如需詳細資訊,請參閱 ASP.NET 中的 .NET 泛型主機

非 Web 案例

一般主機允許其他類型的應用程式,使用交叉剪輯架構延伸模組,例如記錄、相依性插入 (DI)、設定與應用程式存留期管理。 如需詳細資訊,請參閱 ASP.NET Core 中的 .NET 泛型主機,以及在 ASP.NET Core 中使用託管服務的背景工作

伺服器

ASP.NET Core 應用程式使用 HTTP 伺服器實作來接聽 HTTP 要求。 伺服器會把向應用程式發出的要求作為一組要求功能,合併成一個 HttpContext

ASP.NET Core 隨附下列伺服器實作:

  • Kestrel 是跨平台的網頁伺服器。 Kestrel 通常會使用 IIS 在反向 Proxy 設定中執行。 在 ASP.NET Core 2.0 或更新版本中,Kestrel 可以做為直接向網際網路公開的公眾 Edge Server 執行。
  • IIS HTTP 伺服器則是適用於使用 IIS Windows 的伺服器。 透過此伺服器,ASP.NET Core 應用程式及 IIS 便可以在相同處理序中執行。
  • HTTP.sys 則是適用於並未搭配 IIS 使用 Windows 的伺服器。

如需詳細資訊,請參閱在 ASP.NET Core 中實作網頁伺服器

組態

ASP.NET Core 提供組態架構,可從組態提供者的已排序集合中,以成對名稱和數值的形式取得設定。 您可以使用各種來源的內建組態提供者,例如 .json 檔案、.xml 檔案、環境變數及命令列引數。 撰寫自訂組態提供者以支援其他來源。

根據預設,ASP.NET Core 應用程式會設定為從 appsettings.json、環境變數、命令列等進行讀取。 載入應用程式的組態時,來自環境變數的值會覆寫來自 appsettings.json 的值。

讀取相關設定值的慣用方式是使用選項模式 (部分機器翻譯)。 如需詳細資訊,請參閱使用選項模式繫結階層式設定資料

針對管理保密組態資料 (例如密碼),.NET Core 提供祕密管理員。 針對生產祕密,我們建議使用 Azure Key Vault

如需詳細資訊,請參閱 ASP.NET Core 中的組態

環境

執行環境 (例如 DevelopmentStagingProduction) 是 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,此 API 能與各種內建和第三方記錄提供者搭配使用。 可用的提供者包括:

  • 主控台
  • 偵錯
  • Windows 上的事件追蹤
  • Windows 事件記錄檔
  • TraceSource
  • Azure App Service
  • Azure Application Insights

若要建立記錄,ILogger<TCategoryName>請從相依性插入 (DI) 和通話記錄方法 (例如 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,但有些記錄提供者會將這些欄位傳送至資料存放區做為個別欄位。 這項功能可讓記錄提供者實作 semantic logging (語意記錄),又稱為 structured logging (結構化記錄)

如需詳細資料,請參閱 .NET Core 與 ASP.NET Core 中的記錄

路由

「路由」是一種對應到處理常式的 URL 模式。 處理常式通常是 Razor 頁面、MVC 控制器中的動作方法,或是中介軟體。 ASP.NET Core 路由可讓您控制您應用程式使用的 URL。

如需詳細資訊,請參閱 ASP.NET Core 中的路線規劃

錯誤處理

ASP.NET Core 具有處理錯誤的內建功能,例如:

  • 開發人員例外狀況頁面
  • 自訂錯誤頁面
  • 靜態狀態碼頁面
  • 啟動例外狀況處理

如需詳細資訊,請參閱處理 ASP.NET Core 中的錯誤

發出 HTTP 要求

IHttpClientFactory 的實作可用於建立 HttpClient 執行個體。 Factory:

  • 提供一個集中位置以便命名和設定邏輯 HttpClient 執行個體。 例如,註冊並設定 Github 用戶端以存取 GitHub。 註冊並設定預設用戶端以供其他用途使用。
  • 支援註冊及多個委派處理常式的鏈結,以用於建置傳出要求中介軟體管線。 此模式與 ASP.NET Core 的輸入中介軟體管線相似。 模式提供一個機制來管理 HTTP 要求的跨領域關注,包括快取、錯誤處理、序列化和記錄。
  • Polly 整合,Polly 是一種熱門的協力廠商程式庫,用於進行暫時性的錯誤處理。
  • 管理基礎 HttpClientHandler 執行個體的共用和存留期,以避免在手動管理 HttpClient 存留期時,發生的常見 DNS 問題。
  • 針對透過處理站所建立之用戶端傳送的所有要求,新增可設定的記錄體驗 (透過 ILogger)。

如需詳細資訊,請參閱在 ASP.NET Core 中使用 IHttpClientFactory 發出 HTTP 要求

內容根目錄

內容根目錄是下列項目的基底路徑:

  • 裝載應用程式的可執行檔 (.exe)。
  • 構成應用程式 (.dll) 的已編譯組件。
  • 應用程式使用的內容檔案,例如:
    • Razor 檔案 (.cshtml.razor)
    • 組態檔 (.json.xml)
    • 資料檔案 (.db)
  • Web 根目錄,通常是 wwwroot 資料夾。

在開發期間,內容根目錄預設為專案的根目錄。 此目錄也是應用程式內容檔案和 Web 根目錄的基底路徑。 指定不同的內容根目錄,方法是在建置主機時設定其路徑。 如需詳細資訊,請參閱內容根

Web 根目錄

Web 根目錄是公用靜態資源檔的基底路徑,例如:

  • 樣式表單 (.css)
  • JavaScript (.js)
  • 映像 (.png.jpg)

根據預設,靜態檔案只會處理來自 Web 根目錄及其子目錄的檔案。 Web 根路徑預設為 {content root}/wwwroot。 指定不同的 Web 根目錄,方法是在建置主機時設定其路徑。 如需詳細資訊,請參閱 Web 根目錄

防止在 wwwroot 中使用專案檔中的>來發佈檔案。 下列範例會防止在 wwwroot/local 及其子目錄中發佈內容:

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

在 Razor.cshtml 檔案中,tilde-slash (~/) 會指向 Web 根目錄。 開頭為 ~/ 的路徑稱為虛擬路徑

如需詳細資訊,請參閱 ASP.NET Core 中的靜態檔案

本文提供建置 ASP.NET Core 應用程式的基本概念概觀,包括相依性插入 (DI)、設定、中介軟體等等。

如需 Blazor 基礎知識指引 (其會新增或取代此節點中的指引),請參閱 ASP.NET Core Blazor 基本概念

Program.cs

使用 Web 範本建立的 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.Servicesbuilder.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 中介軟體

Host

在啟動時,ASP.NET Core 應用程式會建置一個「主機」。 主機會封裝所有應用程式的資源,例如:

  • HTTP 伺服器實作
  • 中介軟體元件
  • 記錄
  • 相依性插入 (服務)
  • 組態

有三個不同的主機能夠執行 ASP.NET Core 應用程式:

建議使用 ASP.NET Core WebApplicationWebApplicationBuilder 類型,並用於所有 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
  • 將記錄輸出傳送到主控台及偵錯提供者。

非 Web 案例

一般主機允許其他類型的應用程式,使用交叉剪輯架構延伸模組,例如記錄、相依性插入 (DI)、設定與應用程式存留期管理。 如需詳細資訊,請參閱 ASP.NET Core 中的 .NET 泛型主機,以及在 ASP.NET Core 中使用託管服務的背景工作

伺服器

ASP.NET Core 應用程式使用 HTTP 伺服器實作來接聽 HTTP 要求。 伺服器會把向應用程式發出的要求作為一組要求功能,合併成一個 HttpContext

ASP.NET Core 隨附下列伺服器實作:

  • Kestrel 是跨平台的網頁伺服器。 Kestrel 通常會使用 IIS 在反向 Proxy 設定中執行。 在 ASP.NET Core 2.0 或更新版本中,Kestrel 可以做為直接向網際網路公開的公眾 Edge Server 執行。
  • IIS HTTP 伺服器則是適用於使用 IIS Windows 的伺服器。 透過此伺服器,ASP.NET Core 應用程式及 IIS 便可以在相同處理序中執行。
  • HTTP.sys 則是適用於並未搭配 IIS 使用 Windows 的伺服器。

如需詳細資訊,請參閱在 ASP.NET Core 中實作網頁伺服器

組態

ASP.NET Core 提供組態架構,可從組態提供者的已排序集合中,以成對名稱和數值的形式取得設定。 您可以使用各種來源的內建組態提供者,例如 .json 檔案、.xml 檔案、環境變數及命令列引數。 撰寫自訂組態提供者以支援其他來源。

根據預設,ASP.NET Core 應用程式會設定為從 appsettings.json、環境變數、命令列等進行讀取。 載入應用程式的組態時,來自環境變數的值會覆寫來自 appsettings.json 的值。

針對管理保密組態資料 (例如密碼),.NET Core 提供祕密管理員。 針對生產祕密,我們建議使用 Azure Key Vault

如需詳細資訊,請參閱 ASP.NET Core 中的組態

環境

ASP.NET Core 中提供執行環境,例如 DevelopmentStagingProduction。 透過設定 ASPNETCORE_ENVIRONMENT 環境變數來指定應用程式執行的環境。 ASP.NET Core 會在應用程式啟動時讀取環境變數,然後將值儲存在 IWebHostEnvironment 實作中。 您可在應用程式中透過相依性插入 (DI) 取得此實作。

下列範例會在 環境中執行時,設定例外處理常式和 Development 中介軟體:

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,此 API 能與各種內建和第三方記錄提供者搭配使用。 可用的提供者包括:

  • 主控台
  • 偵錯
  • Windows 上的事件追蹤
  • Windows 事件記錄檔
  • TraceSource
  • Azure App Service
  • Azure Application Insights

若要建立記錄,ILogger<TCategoryName>請從相依性插入 (DI) 和通話記錄方法 (例如 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 頁面、MVC 控制器中的動作方法,或是中介軟體。 ASP.NET Core 路由可讓您控制您應用程式使用的 URL。

ASP.NET Core Web 應用程式範本所產生的下列程式碼會呼叫 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 要求

IHttpClientFactory 的實作可用於建立 HttpClient 執行個體。 Factory:

  • 提供一個集中位置以便命名和設定邏輯 HttpClient 執行個體。 例如,註冊並設定 Github 用戶端以存取 GitHub。 註冊並設定預設用戶端以供其他用途使用。
  • 支援註冊及多個委派處理常式的鏈結,以用於建置傳出要求中介軟體管線。 此模式與 ASP.NET Core 的輸入中介軟體管線相似。 模式提供一個機制來管理 HTTP 要求的跨領域關注,包括快取、錯誤處理、序列化和記錄。
  • Polly 整合,Polly 是一種熱門的協力廠商程式庫,用於進行暫時性的錯誤處理。
  • 管理基礎 HttpClientHandler 執行個體的共用和存留期,以避免在手動管理 HttpClient 存留期時,發生的常見 DNS 問題。
  • 針對透過處理站所建立之用戶端傳送的所有要求,新增可設定的記錄體驗 (透過 ILogger)。

如需詳細資訊,請參閱在 ASP.NET Core 中使用 IHttpClientFactory 發出 HTTP 要求

內容根目錄

內容根目錄是下列項目的基底路徑:

  • 裝載應用程式的可執行檔 (.exe)。
  • 構成應用程式 (.dll) 的已編譯組件。
  • 應用程式使用的內容檔案,例如:
    • Razor 檔案 (.cshtml.razor)
    • 組態檔 (.json.xml)
    • 資料檔案 (.db)
  • Web 根目錄,通常是 wwwroot 資料夾。

在開發期間,內容根目錄預設為專案的根目錄。 此目錄也是應用程式內容檔案和 Web 根目錄的基底路徑。 指定不同的內容根目錄,方法是在建置主機時設定其路徑。 如需詳細資訊,請參閱內容根

Web 根目錄

Web 根目錄是公用靜態資源檔的基底路徑,例如:

  • 樣式表單 (.css)
  • JavaScript (.js)
  • 映像 (.png.jpg)

根據預設,靜態檔案只會處理來自 Web 根目錄及其子目錄的檔案。 Web 根路徑預設為 {content root}/wwwroot。 指定不同的 Web 根目錄,方法是在建置主機時設定其路徑。 如需詳細資訊,請參閱 Web 根目錄

防止在 wwwroot 中使用專案檔中的>來發佈檔案。 下列範例會防止在 wwwroot/local 及其子目錄中發佈內容:

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

在 Razor.cshtml 檔案中,~/ 會指向 Web 根目錄。 開頭為 ~/ 的路徑稱為虛擬路徑

如需詳細資訊,請參閱 ASP.NET Core 中的靜態檔案

其他資源