基本 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 類別的新執行個體。

使用連接埠

使用 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();