Aplikace WebApplication a WebApplicationBuilder v aplikacích s minimálním rozhraním API

WebApplication

Následující kód je generován šablonou ASP.NET Core:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Předchozí kód lze vytvořit prostřednictvím dotnet new web příkazového řádku nebo výběrem prázdné webové šablony v sadě Visual Studio.

Následující kód vytvoří WebApplication (app) bez explicitního vytvoření WebApplicationBuilder:

var app = WebApplication.Create(args);

app.MapGet("/", () => "Hello World!");

app.Run();

WebApplication.Create inicializuje novou instanci WebApplication třídy s předkonfigurovanými výchozími nastaveními.

Práce s porty

Při vytvoření webové aplikace pomocí sady Visual Studio nebo dotnet newProperties/launchSettings.json se vytvoří soubor, který určuje porty, na které aplikace reaguje. V ukázkách nastavení portů, které následují, vrátí spuštění aplikace ze sady Visual Studio dialogové okno Unable to connect to web server 'AppName's chybou . Visual Studio vrátí chybu, protože očekává port zadaný v Properties/launchSettings.jsonaplikaci, ale aplikace používá port určený app.Run("http://localhost:3000"). Z příkazového řádku spusťte následující ukázky změn portů.

Následující části nastavují port, na který aplikace reaguje.

var app = WebApplication.Create(args);

app.MapGet("/", () => "Hello World!");

app.Run("http://localhost:3000");

V předchozím kódu aplikace reaguje na port 3000.

Několik portů

V následujícím kódu aplikace reaguje na port 3000 a 4000.

var app = WebApplication.Create(args);

app.Urls.Add("http://localhost:3000");
app.Urls.Add("http://localhost:4000");

app.MapGet("/", () => "Hello World");

app.Run();

Nastavení portu z příkazového řádku

Následující příkaz způsobí, že aplikace reaguje na port 7777:

dotnet run --urls="https://localhost:7777"

Kestrel Pokud je koncový bod také nakonfigurovaný v appsettings.json souboru, appsettings.json použije se zadaná adresa URL. Další informace najdete v tématu Kestrel Konfigurace koncového bodu.

Čtení portu z prostředí

Následující kód načte port z prostředí:

var app = WebApplication.Create(args);

var port = Environment.GetEnvironmentVariable("PORT") ?? "3000";

app.MapGet("/", () => "Hello World");

app.Run($"http://localhost:{port}");

Upřednostňovaným způsobem nastavení portu z prostředí je použití ASPNETCORE_URLS proměnné prostředí, která je znázorněna v následující části.

Nastavení portů prostřednictvím proměnné prostředí ASPNETCORE_URLS

Proměnná ASPNETCORE_URLS prostředí je k dispozici pro nastavení portu:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS podporuje více adres URL:

ASPNETCORE_URLS=http://localhost:3000;https://localhost:5000

Naslouchání na všech rozhraních

Následující ukázky ukazují naslouchání na všech rozhraních.

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

Naslouchání všem rozhraním pomocí ASPNETCORE_URLS

Předchozí ukázky můžou použít ASPNETCORE_URLS

ASPNETCORE_URLS=http://*:3000;https://+:5000;http://0.0.0.0:5005

Naslouchání všem rozhraním pomocí ASPNETCORE_HTTPS_PORTS

Předchozí ukázky mohou používat ASPNETCORE_HTTPS_PORTS a ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Další informace najdete v tématu Konfigurace koncových bodů pro webový server ASP.NET Core Kestrel .

Zadání HTTPS s vývojovým certifikátem

var app = WebApplication.Create(args);

app.Urls.Add("https://localhost:3000");

app.MapGet("/", () => "Hello World");

app.Run();

Další informace o vývojovém certifikátu najdete v tématu Důvěryhodnost vývojového certifikátu ASP.NET Core HTTPS ve Windows a macOS.

Zadání HTTPS pomocí vlastního certifikátu

Následující části ukazují, jak zadat vlastní certifikát pomocí appsettings.json souboru a prostřednictvím konfigurace.

Zadání vlastního certifikátu pomocí appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "Certificates": {
      "Default": {
        "Path": "cert.pem",
        "KeyPath": "key.pem"
      }
    }
  }
}

Zadání vlastního certifikátu prostřednictvím konfigurace

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

Použití rozhraní API pro certifikáty

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

Čtení prostředí

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

Další informace o používání prostředí najdete v tématu Použití více prostředí v ASP.NET Core

Konfigurace

Následující kód čte z konfiguračního systému:

var app = WebApplication.Create(args);

var message = app.Configuration["HelloKey"] ?? "Config failed!";

app.MapGet("/", () => message);

app.Run();

Další informace najdete v tématu Konfigurace v ASP.NET Core

Protokolování

Následující kód zapíše zprávu do protokolu při spuštění aplikace:

var app = WebApplication.Create(args);

app.Logger.LogInformation("The app started");

app.MapGet("/", () => "Hello World");

app.Run();

Další informace najdete v tématu Protokolování v .NET Core a ASP.NET Core

Přístup ke kontejneru injektáže závislostí (DI)

Následující kód ukazuje, jak získat služby z kontejneru DI během spouštění aplikace:

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

Následující kód ukazuje, jak přistupovat ke klíčům z kontejneru DI pomocí atributu [FromKeyedServices] :

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.";
}

Další informace o DI naleznete v tématu Injektáž závislostí v ASP.NET Core.

WebApplicationBuilder

Tato část obsahuje vzorový kód používající WebApplicationBuilder.

Změna kořenového adresáře obsahu, názvu aplikace a prostředí

Následující kód nastaví kořen obsahu, název aplikace a prostředí:

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 inicializuje novou instanci třídy WebApplicationBuilder s předkonfigurovanými výchozími hodnotami.

Další informace najdete v tématu ASP.NET Základní základní přehled

Změna kořenového adresáře obsahu, názvu aplikace a prostředí pomocí proměnných prostředí nebo příkazového řádku

Následující tabulka ukazuje proměnnou prostředí a argument příkazového řádku použitý ke změně kořenového adresáře obsahu, názvu aplikace a prostředí:

funkce	Proměnná prostředí	Argument příkazového řádku
Název aplikace	ASPNETCORE_APPLICATIONNAME	--applicationName
Název prostředí	ASPNETCORE_ENVIRONMENT	--Prostředí
Kořen obsahu	ASPNETCORE_CONTENTROOT	--contentRoot

Přidání zprostředkovatelů konfigurace

Následující ukázka přidá zprostředkovatele konfigurace INI:

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddIniFile("appsettings.ini");

var app = builder.Build();

Podrobné informace najdete v tématu Zprostředkovatelé konfigurace souborů v části Konfigurace v ASP.NET Core.

Konfigurace čtení

Ve výchozím nastavení WebApplicationBuilder konfigurace čtení z více zdrojů, včetně:

• appSettings.json a appSettings.{environment}.json
• Proměnné prostředí
• Příkazový řádek

Úplný seznam přečtených zdrojů konfigurace najdete v tématu Výchozí konfigurace v konfiguraci v ASP.NET Core.

Následující kód načte HelloKey z konfigurace a zobrazí hodnotu v koncovém / bodu. Pokud má konfigurační hodnota hodnotu null, je "Hello" přiřazeno k message:

var builder = WebApplication.CreateBuilder(args);

var message = builder.Configuration["HelloKey"] ?? "Hello";

var app = builder.Build();

app.MapGet("/", () => message);

app.Run();

Čtení prostředí

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    Console.WriteLine($"Running in development.");
}

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Přidání zprostředkovatelů protokolování

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

Přidání služeb

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

Přizpůsobení nástroje IHostBuilder

K existujícím metodám IHostBuilder rozšíření lze přistupovat pomocí vlastnosti Host:

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

Přizpůsobení IWebHostBuilderu

Metody rozšíření lze IWebHostBuilder získat přístup pomocí WebApplicationBuilder.WebHost vlastnost.

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

Změna webového kořenového adresáře

Ve výchozím nastavení je kořenový adresář webu relativní ke kořenovému wwwroot adresáři obsahu ve složce. Web root je místo, kde middleware statických souborů hledá statické soubory. Kořenový adresář webu lze změnit pomocí WebHostOptionspříkazového řádku nebo pomocí UseWebRoot metody:

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    // Look for static files in webroot
    WebRootPath = "webroot"
});

var app = builder.Build();

app.Run();

Kontejner injektáže vlastních závislostí (DI)

Následující příklad používá 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();

Přidání middlewaru

Jakýkoli existující middleware ASP.NET Core je možné nakonfigurovat na :WebApplication

var app = WebApplication.Create(args);

// Setup the file server to serve static files.
app.UseFileServer();

app.MapGet("/", () => "Hello World!");

app.Run();

Další informace najdete v tématu ASP.NET Core Middleware

Stránka výjimky pro vývojáře

WebApplication.CreateBuilder inicializuje novou instanci WebApplicationBuilder třídy s předkonfigurovanými výchozími nastaveními. Stránka výjimky vývojáře je povolená v předkonfigurovaných výchozích nastaveních. Když se ve vývojovém prostředí spustí následující kód, přejdete k / vykreslení popisné stránky, která zobrazí výjimku.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/", () =>
{
    throw new InvalidOperationException("Oops, the '/' route has thrown an exception.");
});

app.Run();