共用方式為


基本 API 應用程式中的 WebApplication 和 WebApplicationBuilder

注意

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

警告

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

重要

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

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

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 中自動新增下列中介軟體:

下列程式碼實際上是將自動中介軟體新增至應用程式所產生的內容:

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 => {});

在某些情況下,應用程式的預設中介軟體設定不正確,而且需要修改。 例如,應該在 UseAuthenticationUseAuthorization 之前呼叫 UseCors。 如果呼叫 UseCors,則應用程式需要呼叫 UseAuthenticationUseAuthorization

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

如果中介軟體應在路由比對發生之前執行,則應該呼叫 UseRouting,而且中介軟體應該放在對 UseRouting 的呼叫之前。 UseEndpoints 在此案例中並非必要項目,因為它會如先前所述自動新增:

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// other middleware and endpoints

新增終端中介軟體時:

  • 中介軟體必須在 UseEndpoints 之後新增。
  • 應用程式必須呼叫 UseRoutingUseEndpoints,讓終端中介軟體可以放在正確的位置。
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

多個連接埠

在下列程式碼中,應用程式會回應連接埠 30004000

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.jsonappSettings.{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 中自動新增下列中介軟體:

下列程式碼實際上是將自動中介軟體新增至應用程式所產生的內容:

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 => {});

在某些情況下,應用程式的預設中介軟體設定不正確,而且需要修改。 例如,應該在 UseAuthenticationUseAuthorization 之前呼叫 UseCors。 如果呼叫 UseCors,則應用程式需要呼叫 UseAuthenticationUseAuthorization

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

如果中介軟體應在路由比對發生之前執行,則應該呼叫 UseRouting,而且中介軟體應該放在對 UseRouting 的呼叫之前。 UseEndpoints 在此案例中並非必要項目,因為它會如先前所述自動新增:

app.Use((context, next) =>
{
    return next(context);
});

app.UseRouting();

// other middleware and endpoints

新增終端中介軟體時:

  • 中介軟體必須在 UseEndpoints 之後新增。
  • 應用程式必須呼叫 UseRoutingUseEndpoints,讓終端中介軟體可以放在正確的位置。
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

多個連接埠

在下列程式碼中,應用程式會回應連接埠 30004000

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_PORTSASPNETCORE_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.jsonappSettings.{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();