WebApplication und WebApplicationBuilder in Minimal-API-Apps

WebApplication

Der folgende Code wird von einer ASP.NET Core-Vorlage generiert:

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

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

app.Run();

Der vorstehende Code kann über dotnet new web in der Befehlszeile oder durch Auswahl der leeren Webvorlage in Visual Studio erstellt werden.

Mit dem folgenden Code wird eine WebApplication (app) erstellt, ohne explizit einen WebApplicationBuilder zu erstellen:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create initialisiert eine neue Instanz der WebApplication-Klasse mit vorkonfigurierten Standardwerten.

Arbeiten mit Ports

Beim Erstellen einer Web-App mit Visual Studio oder dotnet new wird eine Datei Properties/launchSettings.json erstellt, die die Ports angibt, an denen die Anwendung antwortet. In den folgenden Beispielen für Porteinstellungen wird beim Ausführen der App in Visual Studio ein Fehlerdialogfeld Unable to connect to web server 'AppName' angezeigt. Visual Studio gibt einen Fehler zurück, da der in Properties/launchSettings.jsonangegebene Port erwartet wird, die App jedoch den von app.Run("http://localhost:3000") angegebenen Port verwendet. Führen Sie die folgenden Beispiele für Portänderungen über die Befehlszeile aus.

In den folgenden Abschnitten wird der Port festgelegt, auf den die App reagiert.

var app = WebApplication.Create(args);

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

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

Im vorangehenden Code antwortet die App auf Port 3000.

Mehrere Ports

Im folgenden Code antwortet die App auf Port 3000 und 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Festlegen des Ports über die Befehlszeile

Mit dem folgenden Befehl antwortet die App auf Port 7777:

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

Wenn der Endpunkt Kestrel ebenfalls in der Datei appsettings.json konfiguriert ist, wird die in der Datei appsettings.json angegebene URL verwendet. Weitere Informationen finden Sie unter Kestrel-Endpunktkonfiguration.

Lesen des Ports aus der Umgebung

Der folgende Code liest den Port aus der Umgebung:

var app = WebApplication.Create(args);

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

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

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

Die bevorzugte Methode zur Festlegung des Ports über die Umgebung ist die Verwendung der Umgebungsvariablen ASPNETCORE_URLS, die im folgenden Abschnitt beschrieben wird.

Festlegen der Ports über die ASPNETCORE_URLS-Umgebungsvariable

Für die Festlegung des Ports steht die Umgebungsvariable ASPNETCORE_URLS zur Verfügung:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS unterstützt mehrere URLs:

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

Lauschen an allen Schnittstellen

Die folgenden Beispiele veranschaulichen das Lauschen an allen Schnittstellen.

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

Lauschen an allen Schnittstellen mit ASPNETCORE_URLS

In den vorherigen Beispielen kann ASPNETCORE_URLS verwendet werden.

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

Überwachen aller Schnittstellen mithilfe von ASPNETCORE_HTTPS_PORTS

In den vorherigen Beispielen können ASPNETCORE_HTTPS_PORTS und ASPNETCORE_HTTP_PORTS verwendet werden.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Weitere Informationen finden Sie unter Konfigurieren von Endpunkten für den Kestrel-Webserver von ASP.NET Core.

Angeben von HTTPS mit Entwicklungszertifikat

var app = WebApplication.Create(args);

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

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

app.Run();

Weitere Informationen über das Entwicklungszertifikat finden Sie unter Vertrauen Sie dem ASP.NET Core-HTTPS-Entwicklungszertifikat unter Windows und macOS.

Angeben von HTTPS mithilfe eines benutzerdefinierten Zertifikats

Die folgenden Abschnitte zeigen, wie das benutzerdefinierte Zertifikat mithilfe der Datei appsettings.json und über die Konfiguration angegeben wird.

Angeben des benutzerdefinierten Zertifikats mit appsettings.json

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

Angeben des benutzerdefinierten Zertifikats über die Konfiguration

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

Verwenden der Zertifikat-APIs

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

Lesen der Umgebung

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

Weitere Informationen zur Verwendung der Umgebung finden Sie unter Verwenden mehrerer Umgebungen in ASP.NET Core.

Konfiguration

Der folgende Code liest Informationen aus dem Konfigurationssystem:

var app = WebApplication.Create(args);

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

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

app.Run();

Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.

Protokollierung

Der folgende Code schreibt eine Meldung in das Anwendungsstartprotokoll:

var app = WebApplication.Create(args);

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

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

app.Run();

Weitere Informationen finden Sie unter Protokollieren in .NET Core und ASP.NET Core.

Zugreifen auf den Container für Abhängigkeitsinjektion

Der folgende Code zeigt, wie Dienste während des Anwendungsstarts aus dem Abhängigkeitsinjektionscontainer abzurufen sind:

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

Der folgende Code zeigt, wie Sie mit dem [FromKeyedServices]-Attribut auf Schlüssel aus dem DI-Container (Dependency Injection, Abhängigkeitsinjektion) zugreifen können:

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

Weitere Informationen zu DI finden Sie unter Abhängigkeitsinjektion in ASP.NET Core.

WebApplicationBuilder

Dieser Abschnitt enthält Beispielcode unter Verwendung von WebApplicationBuilder.

Ändern von Inhaltsstamm, Anwendungsname und Umgebung

Der folgende Code legt den Inhaltsstamm, den Anwendungsnamen und die Umgebung fest:

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 Initialisiert eine neue Instanz der WebApplicationBuilder-Klasse mit vorkonfigurierten Standardwerten.

Weitere Informationen finden Sie unter ASP.NET Core – Grundlagenübersicht.

Ändern von Inhaltsstamm, App-Name und Umgebung über Umgebungsvariablen oder Befehlszeile

Die folgende Tabelle zeigt die Umgebungsvariablen und Befehlszeilenargumente, die zum Ändern von Inhaltsstamm, Anwendungsname und Umgebung verwendet werden:

Feature	Umgebungsvariable	Befehlszeilenargument
Anwendungsname	ASPNETCORE_APPLICATIONNAME	--applicationName
Umgebungsname	ASPNETCORE_ENVIRONMENT	--environment
Inhaltsstammverzeichnis	ASPNETCORE_CONTENTROOT	--contentRoot

Hinzufügen von Konfigurationsanbietern

Im folgenden Beispiel wird der INI-Konfigurationsanbieter hinzugefügt:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Ausführliche Informationen finden Sie unter Dateikonfigurationsanbieter in Konfiguration in ASP.NET Core.

Lesen der Konfiguration

Standardmäßig liest die WebApplicationBuilder die Konfiguration aus mehreren Quellen, darunter:

• appSettings.json und appSettings.{environment}.json
• Umgebungsvariablen
• Die Befehlszeile

Eine vollständige Liste der gelesenen Konfigurationsquellen finden Sie unter Standardkonfiguration in Konfiguration in ASP.NET Core.

Der folgende Code liest HelloKey aus der Konfiguration und zeigt den Wert am Endpunkt / an. Wenn der Konfigurationswert NULL ist, wird „Hello“ message zugewiesen:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Lesen der Umgebung

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Hinzufügen von Protokollierungsanbietern

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

Hinzufügen von Diensten

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

Anpassen von IHostBuilder

Vorhandene Erweiterungsmethoden für IHostBuilder können über die Host-Eigenschaft aufgerufen werden:

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

Anpassen von IWebHostBuilder

Erweiterungsmethoden für IWebHostBuilder können über die Eigenschaft WebApplicationBuilder.WebHost aufgerufen werden.

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

Ändern des Webstamms

Standardmäßig ist der Webstamm relativ zum Inhaltsstamm im Ordner wwwroot angegeben. Im Webstamm sucht die Middleware für statische Dateien nach statischen Dateien. Der Webstamm kann mit WebHostOptions, der Befehlszeile oder mit der Methode UseWebRoot geändert werden:

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

var app = builder.Build();

app.Run();

Container für benutzerdefinierte Abhängigkeitsinjektion

Im folgenden Beispiel wird Autofac verwendet:

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

Hinzufügen von Middleware

Für die WebApplication kann eine beliebige vorhandene ASP.NET Core-Middleware konfiguriert werden:

var app = WebApplication.Create(args);

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

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

app.Run();

Weitere Informationen finden Sie unter ASP.NET Core-Middleware.

Seite mit Ausnahmen für Entwickler

WebApplication.CreateBuilder initialisiert eine neue Instanz der WebApplicationBuilder-Klasse mit vorkonfigurierten Standardwerten. Die Seite mit Ausnahmen für Entwickler ist in den vorkonfigurierten Standardwerten aktiviert. Durch Ausführung des folgende Codes in der Entwicklungsumgebung wird beim Navigieren zu / eine benutzerfreundliche Seite geöffnet, auf der die Ausnahme angezeigt wird.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();