最小 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”模板来创建前面的代码。

以下代码创建 WebApplication (app)，而无需显式创建 WebApplicationBuilder：

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 中的配置

Logging

以下代码在应用程序启动时将消息写入日志：

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 基础知识概述

使用环境变量或命令行更改内容根、应用程序名称和环境

下表显示了用于更改内容根、应用程序名称和环境的环境变量及命令行参数：

feature	环境变量	命令行参数
应用程序名称	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

可以使用 IHostBuilder访问 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

可以使用 IWebHostBuilder 属性访问 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 根是静态文件中间件查找静态文件的位置。 可以使用 WebHostOptions、命令行或 UseWebRoot 方法更改 Web 根：

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