基本 API 應用程式中的 WebApplication 和 WebApplicationBuilder
WebApplication
下列程式碼是由 ASP.NET Core 範本所產生：
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();
上述程式碼可以在命令列透過 dotnet new web 或在 Visual Studio 中選取空白 Web 範本來建立。
下列程式碼會在未明確建立 WebApplicationBuilder 的情況下建立 WebApplication (app)：
var app = WebApplication.Create(args);
app.MapGet("/", () => "Hello World!");
app.Run();
WebApplication.Create 會使用預先設定的預設值，初始化 WebApplication 類別的新執行個體。
WebApplication 根據特定條件，自動在 中 Minimal API applications 新增下列中間件：
- 當
HostingEnvironment是"Development"，會先新增UseDeveloperExceptionPage。 - 如果使用者程式碼尚未呼叫
UseRouting，且已設定端點 (例如app.MapGet)，則會接著新增UseRouting。 - 如果已設定任何端點，則會在中介軟體管線的結尾新增
UseEndpoints。 - 如果使用者程式碼尚未呼叫
UseAuthentication，且如果可以在服務提供者中偵測到IAuthenticationSchemeProvider，則會在UseRouting之後立即新增UseAuthentication。 使用AddAuthentication時，且使用IServiceProviderIsService偵測到服務，預設會新增IAuthenticationSchemeProvider。 - 如果使用者程式碼尚未呼叫
UseAuthorization，且如果可以在服務提供者中偵測到IAuthorizationHandlerProvider，則會接著新增UseAuthorization。 使用AddAuthorization時，且使用IServiceProviderIsService偵測到服務，預設會新增IAuthorizationHandlerProvider。 - 使用者設定的中介軟體和端點會在
UseRouting和UseEndpoints之間新增。
下列程式碼實際上是將自動中介軟體新增至應用程式所產生的內容：
if (isDevelopment)
{
app.UseDeveloperExceptionPage();
}
app.UseRouting();
if (isAuthenticationConfigured)
{
app.UseAuthentication();
}
if (isAuthorizationConfigured)
{
app.UseAuthorization();
}
// user middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// end user middleware/endpoints
app.UseEndpoints(e => {});
在某些情況下，應用程式的預設中介軟體設定不正確，而且需要修改。 例如，應該在 UseAuthentication 和 UseAuthorization 之前呼叫 UseCors。 如果呼叫 UseCors，則應用程式需要呼叫 UseAuthentication 和 UseAuthorization：
app.UseCors();
app.UseAuthentication();
app.UseAuthorization();
如果中介軟體應在路由比對發生之前執行，則應該呼叫 UseRouting，而且中介軟體應該放在對 UseRouting 的呼叫之前。 UseEndpoints 在此案例中並非必要項目，因為它會如先前所述自動新增：
app.Use((context, next) =>
{
return next(context);
});
app.UseRouting();
// other middleware and endpoints
新增終端中介軟體時：
- 中介軟體必須在
UseEndpoints之後新增。 - 應用程式必須呼叫
UseRouting和UseEndpoints，讓終端中介軟體可以放在正確的位置。
app.UseRouting();
app.MapGet("/", () => "hello world");
app.UseEndpoints(e => {});
app.Run(context =>
{
context.Response.StatusCode = 404;
return Task.CompletedTask;
});
終端中介軟體是會在沒有可處理要求的端點時執行的中介軟體。
使用連接埠
使用 Visual Studio 或 dotnet new 建立 Web 應用程式時，會建立一個 Properties/launchSettings.json 檔案，其指定應用程式回應的連接埠。 在後續的連接埠設定範例中，從 Visual Studio 執行應用程式會傳回錯誤對話方塊 Unable to connect to web server 'AppName'。 Visual Studio 傳回錯誤，因為它預期的是在 Properties/launchSettings.json 中指定的連接埠，但應用程式正在使用 app.Run("http://localhost:3000") 所指定的連接埠。 從命令列執行下列連接埠變更範例。
下列各節會設定應用程式回應的連接埠。
var app = WebApplication.Create(args);
app.MapGet("/", () => "Hello World!");
app.Run("http://localhost:3000");
在上述程式碼中，應用程式會回應連接埠 3000。
多個連接埠
在下列程式碼中，應用程式會回應連接埠 3000 和 4000。
var app = WebApplication.Create(args);
app.Urls.Add("http://localhost:3000");
app.Urls.Add("http://localhost:4000");
app.MapGet("/", () => "Hello World");
app.Run();
從命令列設定連接埠
下列命令會讓應用程式回應連接埠 7777：
dotnet run --urls="https://localhost:7777"
如果 appsettings.json 檔案中也已設定 Kestrel 端點，則會使用 appsettings.json 檔案指定的 URL。 如需詳細資訊，請參閱 Kestrel 端點設定
從環境讀取連接埠
下列程式碼會從環境讀取連接埠：
var app = WebApplication.Create(args);
var port = Environment.GetEnvironmentVariable("PORT") ?? "3000";
app.MapGet("/", () => "Hello World");
app.Run($"http://localhost:{port}");
從環境設定連接埠的偏好方式是使用 ASPNETCORE_URLS 環境變數，如下一節所示。
透過 ASPNETCORE_URLS 環境變數設定連接埠
ASPNETCORE_URLS 環境變數可用來設定連接埠：
ASPNETCORE_URLS=http://localhost:3000
ASPNETCORE_URLS 支援多個 URL：
ASPNETCORE_URLS=http://localhost:3000;https://localhost:5000
如需使用環境的詳細資訊，請參閱在 ASP.NET Core 中使用多個環境
在所有介面上接聽
下列範例示範在所有介面上接聽
http://*:3000
var app = WebApplication.Create(args);
app.Urls.Add("http://*:3000");
app.MapGet("/", () => "Hello World");
app.Run();
http://+:3000
var app = WebApplication.Create(args);
app.Urls.Add("http://+:3000");
app.MapGet("/", () => "Hello World");
app.Run();
http://0.0.0.0:3000
var app = WebApplication.Create(args);
app.Urls.Add("http://0.0.0.0:3000");
app.MapGet("/", () => "Hello World");
app.Run();
使用 ASPNETCORE_URLS 在所有介面上接聽
上述範例可以使用 ASPNETCORE_URLS
ASPNETCORE_URLS=http://*:3000;https://+:5000;http://0.0.0.0:5005
使用開發憑證指定 HTTPS
var app = WebApplication.Create(args);
app.Urls.Add("https://localhost:3000");
app.MapGet("/", () => "Hello World");
app.Run();
如需開發憑證的詳細資訊，請參閱信任 Windows 和 macOS 上的 ASP.NET Core HTTPS 開發憑證。
使用自訂憑證指定 HTTPS
下列各節說明如何使用 appsettings.json 檔案和透過設定指定自訂憑證。
使用 appsettings.json 指定自訂憑證
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*",
"Kestrel": {
"Certificates": {
"Default": {
"Path": "cert.pem",
"KeyPath": "key.pem"
}
}
}
}
透過設定指定自訂憑證
var builder = WebApplication.CreateBuilder(args);
// Configure the cert and the key
builder.Configuration["Kestrel:Certificates:Default:Path"] = "cert.pem";
builder.Configuration["Kestrel:Certificates:Default:KeyPath"] = "key.pem";
var app = builder.Build();
app.Urls.Add("https://localhost:3000");
app.MapGet("/", () => "Hello World");
app.Run();
使用憑證 API
using System.Security.Cryptography.X509Certificates;
var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureKestrel(options =>
{
options.ConfigureHttpsDefaults(httpsOptions =>
{
var certPath = Path.Combine(builder.Environment.ContentRootPath, "cert.pem");
var keyPath = Path.Combine(builder.Environment.ContentRootPath, "key.pem");
httpsOptions.ServerCertificate = X509Certificate2.CreateFromPemFile(certPath,
keyPath);
});
});
var app = builder.Build();
app.Urls.Add("https://localhost:3000");
app.MapGet("/", () => "Hello World");
app.Run();
組態
下列程式碼會從設定系統讀取：
var app = WebApplication.Create(args);
var message = app.Configuration["HelloKey"] ?? "Config failed!";
app.MapGet("/", () => message);
app.Run();
如需詳細資訊，請參閱 ASP.NET Core 中的設定
記錄
下列程式碼會將訊息寫入至應用程式啟動時的記錄檔：
var app = WebApplication.Create(args);
app.Logger.LogInformation("The app started");
app.MapGet("/", () => "Hello World");
app.Run();
如需詳細資訊，請參閱 .NET Core 與 ASP.NET Core 中的記錄
存取相依性插入 (DI) 容器
下列程式碼示範如何在應用程式啟動期間從 DI 容器取得服務：
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddScoped<SampleService>();
var app = builder.Build();
app.MapControllers();
using (var scope = app.Services.CreateScope())
{
var sampleService = scope.ServiceProvider.GetRequiredService<SampleService>();
sampleService.DoSomething();
}
app.Run();
如需詳細資訊，請參閱在 ASP.NET Core 中插入相依性。
WebApplicationBuilder
本節包含使用 WebApplicationBuilder 的範例程式碼。
變更內容根目錄、應用程式名稱和環境
下列程式碼會設定內容根目錄、應用程式名稱和環境：
var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
Args = args,
ApplicationName = typeof(Program).Assembly.FullName,
ContentRootPath = Directory.GetCurrentDirectory(),
EnvironmentName = Environments.Staging,
WebRootPath = "customwwwroot"
});
Console.WriteLine($"Application Name: {builder.Environment.ApplicationName}");
Console.WriteLine($"Environment Name: {builder.Environment.EnvironmentName}");
Console.WriteLine($"ContentRoot Path: {builder.Environment.ContentRootPath}");
Console.WriteLine($"WebRootPath: {builder.Environment.WebRootPath}");
var app = builder.Build();
WebApplication.CreateBuilder 會初始化具有預先設定之預設值的之 WebApplicationBuilder 類別的新執行個體。
如需詳細資訊，請參閱 ASP.NET Core 基礎知識概觀
使用環境變數或命令列來變更內容根目錄、應用程式名稱和環境
下表顯示用來變更內容根目錄、應用程式名稱和環境的環境變數和命令列引數：
| 功能 | 環境變數 | 命令列引數 |
|---|---|---|
| 應用程式名稱 | ASPNETCORE_APPLICATIONNAME | --applicationName |
| 環境名稱 | ASPNETCORE_ENVIRONMENT | --environment |
| 內容根目錄 | ASPNETCORE_CONTENTROOT | --contentRoot |
新增組態提供者
下列範例會新增 INI 設定提供者：
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddIniFile("appsettings.ini");
var app = builder.Build();
如需詳細資訊，請參閱 ASP.NET Core 中的設定中的檔案設定提供者。
讀取設定
依預設，WebApplicationBuilder 會從多個來源讀取設定，包括：
appSettings.json和appSettings.{environment}.json- 環境變數
- 命令列
下列程式碼會從設定讀取 HelloKey，並在 / 端點顯示值。 如果設定值為 null，則會將 "Hello" 指派給 message：
var builder = WebApplication.CreateBuilder(args);
var message = builder.Configuration["HelloKey"] ?? "Hello";
var app = builder.Build();
app.MapGet("/", () => message);
app.Run();
如需讀取的設定來源完整清單，請參閱 ASP.NET Core 中的設定的預設設定
新增記錄提供者
var builder = WebApplication.CreateBuilder(args);
// Configure JSON logging to the console.
builder.Logging.AddJsonConsole();
var app = builder.Build();
app.MapGet("/", () => "Hello JSON console!");
app.Run();
新增服務
var builder = WebApplication.CreateBuilder(args);
// Add the memory cache services.
builder.Services.AddMemoryCache();
// Add a custom scoped service.
builder.Services.AddScoped<ITodoRepository, TodoRepository>();
var app = builder.Build();
自訂 IHostBuilder
您可以使用 Host 屬性來存取 IHostBuilder 上的現有擴充方法：
var builder = WebApplication.CreateBuilder(args);
// Wait 30 seconds for graceful shutdown.
builder.Host.ConfigureHostOptions(o => o.ShutdownTimeout = TimeSpan.FromSeconds(30));
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();
自訂 IWebHostBuilder
您可以使用 WebApplicationBuilder.WebHost 屬性來存取 IWebHostBuilder 上的擴充方法。
var builder = WebApplication.CreateBuilder(args);
// Change the HTTP server implemenation to be HTTP.sys based
builder.WebHost.UseHttpSys();
var app = builder.Build();
app.MapGet("/", () => "Hello HTTP.sys");
app.Run();
變更 Web 根目錄
依預設，Web 根目錄會相對於 wwwroot 資料夾中的內容根目錄。 Web 根目錄是靜態檔案中介軟體尋找靜態檔案的位置。 Web 根目錄可以透過 WebHostOptions、命令列或 UseWebRoot 方法變更：
var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
Args = args,
// Look for static files in webroot
WebRootPath = "webroot"
});
var app = builder.Build();
app.Run();
自訂相依性插入 (DI) 容器
下列範例使用 Autofac：
var builder = WebApplication.CreateBuilder(args);
builder.Host.UseServiceProviderFactory(new AutofacServiceProviderFactory());
// Register services directly with Autofac here. Don't
// call builder.Populate(), that happens in AutofacServiceProviderFactory.
builder.Host.ConfigureContainer<ContainerBuilder>(builder => builder.RegisterModule(new MyApplicationModule()));
var app = builder.Build();
新增中介軟體
您可以在 WebApplication 上設定任何現有的 ASP.NET Core 中介軟體：
var app = WebApplication.Create(args);
// Setup the file server to serve static files.
app.UseFileServer();
app.MapGet("/", () => "Hello World!");
app.Run();
如需詳細資訊，請參閱 ASP.NET Core 中介軟體
開發人員例外頁面
WebApplication.CreateBuilder 會使用預先設定的預設值，初始化 WebApplicationBuilder 類別的新執行個體。 開發人員例外狀況頁面會以預先設定的預設值啟用。 在開發環境中執行下列程式碼時，瀏覽至 / 會轉譯顯示例外狀況的易記頁面。
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () =>
{
throw new InvalidOperationException("Oops, the '/' route has thrown an exception.");
});
app.Run();
WebApplication
下列程式碼是由 ASP.NET Core 範本所產生：
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();
上述程式碼可以在命令列透過 dotnet new web 或在 Visual Studio 中選取空白 Web 範本來建立。
下列程式碼會在未明確建立 WebApplicationBuilder 的情況下建立 WebApplication (app)：
var app = WebApplication.Create(args);
app.MapGet("/", () => "Hello World!");
app.Run();
WebApplication.Create 會使用預先設定的預設值，初始化 WebApplication 類別的新執行個體。
WebApplication 根據特定條件，自動在 中 Minimal API applications 新增下列中間件：
- 當
HostingEnvironment是"Development"，會先新增UseDeveloperExceptionPage。 - 如果使用者程式碼尚未呼叫
UseRouting，且已設定端點 (例如app.MapGet)，則會接著新增UseRouting。 - 如果已設定任何端點，則會在中介軟體管線的結尾新增
UseEndpoints。 - 如果使用者程式碼尚未呼叫
UseAuthentication，且如果可以在服務提供者中偵測到IAuthenticationSchemeProvider，則會在UseRouting之後立即新增UseAuthentication。 使用AddAuthentication時，且使用IServiceProviderIsService偵測到服務，預設會新增IAuthenticationSchemeProvider。 - 如果使用者程式碼尚未呼叫
UseAuthorization，且如果可以在服務提供者中偵測到IAuthorizationHandlerProvider，則會接著新增UseAuthorization。 使用AddAuthorization時，且使用IServiceProviderIsService偵測到服務，預設會新增IAuthorizationHandlerProvider。 - 使用者設定的中介軟體和端點會在
UseRouting和UseEndpoints之間新增。
下列程式碼實際上是將自動中介軟體新增至應用程式所產生的內容：
if (isDevelopment)
{
app.UseDeveloperExceptionPage();
}
app.UseRouting();
if (isAuthenticationConfigured)
{
app.UseAuthentication();
}
if (isAuthorizationConfigured)
{
app.UseAuthorization();
}
// user middleware/endpoints
app.CustomMiddleware(...);
app.MapGet("/", () => "hello world");
// end user middleware/endpoints
app.UseEndpoints(e => {});
在某些情況下，應用程式的預設中介軟體設定不正確，而且需要修改。 例如，應該在 UseAuthentication 和 UseAuthorization 之前呼叫 UseCors。 如果呼叫 UseCors，則應用程式需要呼叫 UseAuthentication 和 UseAuthorization：
app.UseCors();
app.UseAuthentication();
app.UseAuthorization();
如果中介軟體應在路由比對發生之前執行，則應該呼叫 UseRouting，而且中介軟體應該放在對 UseRouting 的呼叫之前。 UseEndpoints 在此案例中並非必要項目，因為它會如先前所述自動新增：
app.Use((context, next) =>
{
return next(context);
});
app.UseRouting();
// other middleware and endpoints
新增終端中介軟體時：
- 中介軟體必須在
UseEndpoints之後新增。 - 應用程式必須呼叫
UseRouting和UseEndpoints，讓終端中介軟體可以放在正確的位置。
app.UseRouting();
app.MapGet("/", () => "hello world");
app.UseEndpoints(e => {});
app.Run(context =>
{
context.Response.StatusCode = 404;
return Task.CompletedTask;
});
終端中介軟體是會在沒有可處理要求的端點時執行的中介軟體。
使用連接埠
使用 Visual Studio 或 dotnet new 建立 Web 應用程式時，會建立一個 Properties/launchSettings.json 檔案，其指定應用程式回應的連接埠。 在後續的連接埠設定範例中，從 Visual Studio 執行應用程式會傳回錯誤對話方塊 Unable to connect to web server 'AppName'。 Visual Studio 傳回錯誤，因為它預期的是在 Properties/launchSettings.json 中指定的連接埠，但應用程式正在使用 app.Run("http://localhost:3000") 所指定的連接埠。 從命令列執行下列連接埠變更範例。
下列各節會設定應用程式回應的連接埠。
var app = WebApplication.Create(args);
app.MapGet("/", () => "Hello World!");
app.Run("http://localhost:3000");
在上述程式碼中，應用程式會回應連接埠 3000。
多個連接埠
在下列程式碼中，應用程式會回應連接埠 3000 和 4000。
var app = WebApplication.Create(args);
app.Urls.Add("http://localhost:3000");
app.Urls.Add("http://localhost:4000");
app.MapGet("/", () => "Hello World");
app.Run();
從命令列設定連接埠
下列命令會讓應用程式回應連接埠 7777：
dotnet run --urls="https://localhost:7777"
如果 appsettings.json 檔案中也已設定 Kestrel 端點，則會使用 appsettings.json 檔案指定的 URL。 如需詳細資訊，請參閱 Kestrel 端點設定
從環境讀取連接埠
下列程式碼會從環境讀取連接埠：
var app = WebApplication.Create(args);
var port = Environment.GetEnvironmentVariable("PORT") ?? "3000";
app.MapGet("/", () => "Hello World");
app.Run($"http://localhost:{port}");
從環境設定連接埠的偏好方式是使用 ASPNETCORE_URLS 環境變數，如下一節所示。
透過 ASPNETCORE_URLS 環境變數設定連接埠
ASPNETCORE_URLS 環境變數可用來設定連接埠：
ASPNETCORE_URLS=http://localhost:3000
ASPNETCORE_URLS 支援多個 URL：
ASPNETCORE_URLS=http://localhost:3000;https://localhost:5000
在所有介面上接聽
下列範例示範在所有介面上接聽
http://*:3000
var app = WebApplication.Create(args);
app.Urls.Add("http://*:3000");
app.MapGet("/", () => "Hello World");
app.Run();
http://+:3000
var app = WebApplication.Create(args);
app.Urls.Add("http://+:3000");
app.MapGet("/", () => "Hello World");
app.Run();
http://0.0.0.0:3000
var app = WebApplication.Create(args);
app.Urls.Add("http://0.0.0.0:3000");
app.MapGet("/", () => "Hello World");
app.Run();
使用 ASPNETCORE_URLS 在所有介面上接聽
上述範例可以使用 ASPNETCORE_URLS
ASPNETCORE_URLS=http://*:3000;https://+:5000;http://0.0.0.0:5005
使用 ASPNETCORE_HTTPS_PORTS 在所有介面上接聽
上述範例可以使用 ASPNETCORE_HTTPS_PORTS 和 ASPNETCORE_HTTP_PORTS。
ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000
如需詳細資訊，請參閱設定 ASP.NET Core Kestrel Web 伺服器的端點
使用開發憑證指定 HTTPS
var app = WebApplication.Create(args);
app.Urls.Add("https://localhost:3000");
app.MapGet("/", () => "Hello World");
app.Run();
如需開發憑證的詳細資訊，請參閱信任 Windows 和 macOS 上的 ASP.NET Core HTTPS 開發憑證。
使用自訂憑證指定 HTTPS
下列各節說明如何使用 appsettings.json 檔案和透過設定指定自訂憑證。
使用 appsettings.json 指定自訂憑證
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*",
"Kestrel": {
"Certificates": {
"Default": {
"Path": "cert.pem",
"KeyPath": "key.pem"
}
}
}
}
透過設定指定自訂憑證
var builder = WebApplication.CreateBuilder(args);
// Configure the cert and the key
builder.Configuration["Kestrel:Certificates:Default:Path"] = "cert.pem";
builder.Configuration["Kestrel:Certificates:Default:KeyPath"] = "key.pem";
var app = builder.Build();
app.Urls.Add("https://localhost:3000");
app.MapGet("/", () => "Hello World");
app.Run();
使用憑證 API
using System.Security.Cryptography.X509Certificates;
var builder = WebApplication.CreateBuilder(args);
builder.WebHost.ConfigureKestrel(options =>
{
options.ConfigureHttpsDefaults(httpsOptions =>
{
var certPath = Path.Combine(builder.Environment.ContentRootPath, "cert.pem");
var keyPath = Path.Combine(builder.Environment.ContentRootPath, "key.pem");
httpsOptions.ServerCertificate = X509Certificate2.CreateFromPemFile(certPath,
keyPath);
});
});
var app = builder.Build();
app.Urls.Add("https://localhost:3000");
app.MapGet("/", () => "Hello World");
app.Run();
讀取環境
var app = WebApplication.Create(args);
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/oops");
}
app.MapGet("/", () => "Hello World");
app.MapGet("/oops", () => "Oops! An error happened.");
app.Run();
如需使用環境的詳細資訊，請參閱在 ASP.NET Core 中使用多個環境
組態
下列程式碼會從設定系統讀取：
var app = WebApplication.Create(args);
var message = app.Configuration["HelloKey"] ?? "Config failed!";
app.MapGet("/", () => message);
app.Run();
如需詳細資訊，請參閱 ASP.NET Core 中的設定
記錄
下列程式碼會將訊息寫入至應用程式啟動時的記錄檔：
var app = WebApplication.Create(args);
app.Logger.LogInformation("The app started");
app.MapGet("/", () => "Hello World");
app.Run();
如需詳細資訊，請參閱 .NET Core 與 ASP.NET Core 中的記錄
存取相依性插入 (DI) 容器
下列程式碼示範如何在應用程式啟動期間從 DI 容器取得服務：
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddScoped<SampleService>();
var app = builder.Build();
app.MapControllers();
using (var scope = app.Services.CreateScope())
{
var sampleService = scope.ServiceProvider.GetRequiredService<SampleService>();
sampleService.DoSomething();
}
app.Run();
下列程式碼示範如何使用 [FromKeyedServices] 屬性從 DI 容器存取金鑰:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddKeyedSingleton<ICache, BigCache>("big");
builder.Services.AddKeyedSingleton<ICache, SmallCache>("small");
var app = builder.Build();
app.MapGet("/big", ([FromKeyedServices("big")] ICache bigCache) => bigCache.Get("date"));
app.MapGet("/small", ([FromKeyedServices("small")] ICache smallCache) => smallCache.Get("date"));
app.Run();
public interface ICache
{
object Get(string key);
}
public class BigCache : ICache
{
public object Get(string key) => $"Resolving {key} from big cache.";
}
public class SmallCache : ICache
{
public object Get(string key) => $"Resolving {key} from small cache.";
}
如需 DI 的詳細資訊，請參閱在 ASP.NET Core 中插入相依性。
WebApplicationBuilder
本節包含使用 WebApplicationBuilder 的範例程式碼。
變更內容根目錄、應用程式名稱和環境
下列程式碼會設定內容根目錄、應用程式名稱和環境：
var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
Args = args,
ApplicationName = typeof(Program).Assembly.FullName,
ContentRootPath = Directory.GetCurrentDirectory(),
EnvironmentName = Environments.Staging,
WebRootPath = "customwwwroot"
});
Console.WriteLine($"Application Name: {builder.Environment.ApplicationName}");
Console.WriteLine($"Environment Name: {builder.Environment.EnvironmentName}");
Console.WriteLine($"ContentRoot Path: {builder.Environment.ContentRootPath}");
Console.WriteLine($"WebRootPath: {builder.Environment.WebRootPath}");
var app = builder.Build();
WebApplication.CreateBuilder 會初始化具有預先設定之預設值的之 WebApplicationBuilder 類別的新執行個體。
如需詳細資訊，請參閱 ASP.NET Core 基礎知識概觀
使用環境變數或命令列來變更內容根目錄、應用程式名稱和環境
下表顯示用來變更內容根目錄、應用程式名稱和環境的環境變數和命令列引數：
| 功能 | 環境變數 | 命令列引數 |
|---|---|---|
| 應用程式名稱 | ASPNETCORE_APPLICATIONNAME | --applicationName |
| 環境名稱 | ASPNETCORE_ENVIRONMENT | --environment |
| 內容根目錄 | ASPNETCORE_CONTENTROOT | --contentRoot |
新增組態提供者
下列範例會新增 INI 設定提供者：
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddIniFile("appsettings.ini");
var app = builder.Build();
如需詳細資訊，請參閱 ASP.NET Core 中的設定中的檔案設定提供者。
讀取設定
依預設，WebApplicationBuilder 會從多個來源讀取設定，包括：
appSettings.json和appSettings.{environment}.json- 環境變數
- 命令列
如需讀取的組態來源完整清單，請參閱 ASP.NET Core 中的組態中的預設組態。
下列程式碼會從設定讀取 HelloKey，並在 / 端點顯示值。 如果設定值為 null，則會將 "Hello" 指派給 message：
var builder = WebApplication.CreateBuilder(args);
var message = builder.Configuration["HelloKey"] ?? "Hello";
var app = builder.Build();
app.MapGet("/", () => message);
app.Run();
讀取環境
var builder = WebApplication.CreateBuilder(args);
if (builder.Environment.IsDevelopment())
{
Console.WriteLine($"Running in development.");
}
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();
新增記錄提供者
var builder = WebApplication.CreateBuilder(args);
// Configure JSON logging to the console.
builder.Logging.AddJsonConsole();
var app = builder.Build();
app.MapGet("/", () => "Hello JSON console!");
app.Run();
新增服務
var builder = WebApplication.CreateBuilder(args);
// Add the memory cache services.
builder.Services.AddMemoryCache();
// Add a custom scoped service.
builder.Services.AddScoped<ITodoRepository, TodoRepository>();
var app = builder.Build();
自訂 IHostBuilder
您可以使用 Host 屬性來存取 IHostBuilder 上的現有擴充方法：
var builder = WebApplication.CreateBuilder(args);
// Wait 30 seconds for graceful shutdown.
builder.Host.ConfigureHostOptions(o => o.ShutdownTimeout = TimeSpan.FromSeconds(30));
var app = builder.Build();
app.MapGet("/", () => "Hello World!");
app.Run();
自訂 IWebHostBuilder
您可以使用 WebApplicationBuilder.WebHost 屬性來存取 IWebHostBuilder 上的擴充方法。
var builder = WebApplication.CreateBuilder(args);
// Change the HTTP server implemenation to be HTTP.sys based
builder.WebHost.UseHttpSys();
var app = builder.Build();
app.MapGet("/", () => "Hello HTTP.sys");
app.Run();
變更 Web 根目錄
依預設，Web 根目錄會相對於 wwwroot 資料夾中的內容根目錄。 Web 根目錄是靜態檔案中介軟體尋找靜態檔案的位置。 Web 根目錄可以透過 WebHostOptions、命令列或 UseWebRoot 方法變更：
var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
Args = args,
// Look for static files in webroot
WebRootPath = "webroot"
});
var app = builder.Build();
app.Run();
自訂相依性插入 (DI) 容器
下列範例使用 Autofac：
var builder = WebApplication.CreateBuilder(args);
builder.Host.UseServiceProviderFactory(new AutofacServiceProviderFactory());
// Register services directly with Autofac here. Don't
// call builder.Populate(), that happens in AutofacServiceProviderFactory.
builder.Host.ConfigureContainer<ContainerBuilder>(builder => builder.RegisterModule(new MyApplicationModule()));
var app = builder.Build();
新增中介軟體
您可以在 WebApplication 上設定任何現有的 ASP.NET Core 中介軟體：
var app = WebApplication.Create(args);
// Setup the file server to serve static files.
app.UseFileServer();
app.MapGet("/", () => "Hello World!");
app.Run();
如需詳細資訊，請參閱 ASP.NET Core 中介軟體
開發人員例外頁面
WebApplication.CreateBuilder 會使用預先設定的預設值，初始化 WebApplicationBuilder 類別的新執行個體。 開發人員例外狀況頁面會以預先設定的預設值啟用。 在開發環境中執行下列程式碼時，瀏覽至 / 會轉譯顯示例外狀況的易記頁面。
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/", () =>
{
throw new InvalidOperationException("Oops, the '/' route has thrown an exception.");
});
app.Run();
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應