ASP.NET Core 基本概念的概觀

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

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

Program.cs

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

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

下列應用程式啟動程式碼支援：

• Razor Pages
• MVC 控制器與檢視
• Web API 與控制器
• 最小 web API

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 中介軟體。

Host

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

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

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

• ASP.NET Core WebApplication，也稱為最小主機
• 結合 ASP.NET Core ConfigureWebHostDefaults 的 .NET 泛型主機
• ASP.NET Core WebHost

建議使用 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、環境變數、命令列引數及其他來源載入組態。
• 將記錄輸出傳送到主控台及偵錯提供者。

非 Web 案例

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

伺服器

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 中實作網頁伺服器。

組態

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

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

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

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

環境

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

下列範例會在未於 Development 環境中執行時，設定例外處理常式和 HTTP 嚴格的傳輸安全性通訊協定 (HSTS) 中介軟體：

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 中的靜態檔案。

其他資源

• WebApplicationBuilder 原始程式碼