共用方式為


ASP.NET Core 基本概念的概觀

注意

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

警告

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

重要

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

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

本文提供建置 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 環境中執行時,設定例外處理常式和 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 中的靜態檔案

其他資源

本文提供建置 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 環境中執行時,設定例外處理常式和 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 中的靜態檔案

其他資源

本文提供建置 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 上執行操作,並叫用管線中下一個中介軟體或終止要求。

依照慣例,中介軟體元件會透過叫用 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 中介軟體

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