ASP.NET Core 基本概念的概觀

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

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

Program.cs

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

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

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

• Blazor Web Apps
• Razor 頁面
• MVC 控制器與檢視
• Web API 與控制器
• 最小 web API

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.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 解析，方法是在 @inject 元件中使用 Razor 指令，如下列範例所示：

@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中的相依性注入。

Middleware

要求處理管線由一系列中介軟體元件所組成。 每個元件會在 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 伺服器實作
• 中介軟體元件
• Logging
• 相依性插入 (服務)
• Configuration

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

• ASP.NET Core WebApplication，也稱為最小主機
• 結合 ASP.NET Core 的 ConfigureWebHostDefaults
• ASP.NET 核心虛擬主機

建議使用 ASP.NET Core WebApplication 和 WebApplicationBuilder 類型，並用於所有 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 整合。
• 從、環境變數、命令列參數和其他組態來源載入設定。
• 將記錄輸出傳送到主控台及偵錯提供者。

非 Web 情境

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

Servers

ASP.NET Core 應用程式使用 HTTP 伺服器實作來接聽 HTTP 要求。 伺服器會將對應用程式的要求呈現為組成 之一組HttpContext。

Windows

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 伺服器。

macOS

ASP.NET Core 提供 Kestrel 跨平台伺服器實作。 在 ASP.NET Core 2.0 或更新版本中，Kestrel 可以做為直接向網際網路公開的公眾 Edge Server 執行。 Kestrel 通常會使用 Nginx 或 Apache 在反向 Proxy 設定中執行。

Linux

ASP.NET Core 提供 Kestrel 跨平台伺服器實作。 在 ASP.NET Core 2.0 或更新版本中，Kestrel 可以做為直接向網際網路公開的公眾 Edge Server 執行。 Kestrel 通常會使用 Nginx 或 Apache 在反向 Proxy 設定中執行。

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

Configuration

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

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

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

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

Environments

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

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

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

如需詳細資訊，請參閱 ASP.NET Core 執行階段環境。

Logging

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

• Console
• Debug
• Windows 上的事件追蹤
• Windows 事件記錄檔
• TraceSource
• Azure App Service
• Azure 應用程式深入解析

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

Routing

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 整合，這是用於短暫性錯誤處理的熱門第三方程式庫。
• 管理基礎 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，其中 {CONTENT ROOT} 佔位元是內容根目錄。 指定不同的 Web 根目錄，方法是在建置主機時設定其路徑。 如需詳細資訊，請參閱 網站根目錄。

防止在專案檔中通過wwwroot發佈<Content>的檔案。 下列範例會防止在 wwwroot/local 及其子目錄中發佈內容：

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

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

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

如何下載範例

許多文章及教學課程都有包含範例程式碼的連結。

1. 下載 ASP.NET 存放庫 zip 檔案。
2. 將 AspNetCore.Docs-main.zip 檔案解壓縮。
3. 若要存取已解壓縮存放庫中的文章範例應用程式，請使用文章範例連結中的 URL 來協助您導覽至範例的資料夾。 通常，文章的範例連結會出現在文章頂端，其中包含連結文字 檢視或下載範例程序代碼。

範例程式碼中的前置處理器指示詞

為了示範多種案例，範例應用程式使用 #define 和 #if-#else/#elif-#endif 前置處理器指示詞，來選擇性地編譯和執行範例程式碼的不同區段。 針對利用此方式的範例，請設定 C# 檔案頂端的 #define 指示詞，以定義您想要執行之案例的相關聯符號。 部分範例會要求在多個檔案的頂端設定符號，以執行案例。

例如下列 #define 符號清單指出其提供四個情節 (每個符號一個情節)。 目前的範例設定會執行 TemplateCode 情節：

#define TemplateCode // or LogFromMain or ExpandDefault or FilterInCode

若要變更此範例，以執行 ExpandDefault 情節，請定義 ExpandDefault 符號，並將剩餘的符號設為註解：

#define ExpandDefault // TemplateCode or LogFromMain or FilterInCode

如需使用 C# 預處理器指示 詞選擇性編譯程式代碼區段的詳細資訊，請參閱 #define （C# 參考） 和 #if （C# 參考） 。

範例程式代碼中的區域

某些範例應用程式包含由 #region 和 #endregion C# 指令包圍的程式碼區段。 檔建置系統會將這些區域插入轉譯的文件主題中。

區域名稱通常包含 「snippet」 一詞。下列範例顯示名為 snippet_WebHostDefaults的區域：

#region snippet_WebHostDefaults
Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    });
#endregion

上述 C# 代碼段會在主題的 Markdown 檔案中使用以下行參考：

[!code-csharp[](sample/SampleApp/Program.cs?name=snippet_WebHostDefaults)]

您可以放心地忽略或移除圍繞程式碼的 #region 和 #endregion 指示詞。 如果您打算執行主題中所述的範例案例，請勿改變這些指示詞內的程序代碼。

如需詳細資訊，請參閱 參與 ASP.NET 文件：程式碼範例。

其他資源

ASP.NET Core Blazor 基本概念