WebApplication und WebApplicationBuilder in ASP.NET Core 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.CreateBuilder initialisiert eine neue Instanz der WebApplicationBuilder Klasse mit vorkonfigurierten Standardwerten:

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

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

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

app.UseRouting();

// other middleware and endpoints

app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Mit Ports arbeiten

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 der App festgelegt.

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 reagiert 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.

Port aus den Umgebungsvariablen lesen

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 Umgebungsvariable ASPNETCORE_URLS

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

Weitere Informationen zur Verwendung der Umgebung finden Sie unter ASP.NET Core Laufzeitumgebungen.

Auf allen Schnittstellen lauschen

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

An allen Schnittstellen mithilfe von ASPNETCORE_URLS lauschen

Die vorherigen Beispiele können folgendes verwenden ASPNETCORE_URLS:

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

HTTPS mit Entwicklungszertifikat angeben

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

Configuration

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.

Logging

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 und ASP.NET Core.

Zugreifen auf den Container für Abhängigkeitsinjektion

Der folgende Code zeigt, wie Dienste beim Anwendungsstart aus dem DI-Container abgerufen werden:

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

Weitere Informationen 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.Create initialisiert eine neue Instanz der WebApplication-Klasse mit vorkonfigurierten Standardwerten.

Weitere Informationen finden Sie unter ASP.NET Core Fundamentals Overview.

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

Die folgende Tabelle zeigt die Umgebungsvariable und das Befehlszeilenargument, das zum Ändern des Inhaltsstamms, des App-Namens und der Umgebung verwendet wird.

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.

Konfiguration lesen

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

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

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

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

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

Dienste hinzufügen

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

Passen Sie IHostBuilder an

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

Passen Sie IWebHostBuilder an

Auf die Erweiterungsmethoden von IWebHostBuilder kann über die Eigenschaft WebApplicationBuilder.WebHost zugegriffen 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();

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

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

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

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

app.UseRouting();

// Other middleware and endpoints

app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Mit Ports arbeiten

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 der App festgelegt.

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 reagiert 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.

Port aus den Umgebungsvariablen lesen

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 Umgebungsvariable ASPNETCORE_URLS

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

Auf allen Schnittstellen lauschen

Die folgenden Beispiele veranschaulichen das Lauschen auf 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();

An allen Schnittstellen mithilfe von ASPNETCORE_URLS lauschen

Die vorherigen Beispiele können folgendes verwenden ASPNETCORE_URLS:

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

Auf allen Schnittstellen mithilfe von ASPNETCORE_HTTP_PORTS und ASPNETCORE_HTTPS_PORTS lauschen

Die vorherigen Beispiele können auch ASPNETCORE_HTTP_PORTS und ASPNETCORE_HTTPS_PORTS verwenden, aber ASPNETCORE_URLS setzt (wenn festgelegt) die folgenden Einstellungen außer Kraft:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Weitere Informationen finden Sie unter Konfigurieren von Endpunkten für Kestrel webserver.

HTTPS mit Entwicklungszertifikat angeben

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 ASP.NET Core Laufzeitumgebungen.

Configuration

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.

Logging

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 und ASP.NET Core.

Zugreifen auf den Container für Abhängigkeitsinjektion

Der folgende Code zeigt, wie Dienste beim Anwendungsstart aus dem DI-Container abgerufen werden:

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 mithilfe des [FromKeyedServices] Attributs auf Schlüssel aus dem DI-Container zugreifen:

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.Create initialisiert eine neue Instanz der WebApplication-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 Umgebungsvariable und das Befehlszeilenargument, das zum Ändern des Inhaltsstamms, des App-Namens und der Umgebung verwendet wird.

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.

Konfiguration lesen

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

Dienste hinzufügen

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

Passen Sie IHostBuilder an

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

Passen Sie IWebHostBuilder an

Auf die Erweiterungsmethoden von IWebHostBuilder kann über die Eigenschaft WebApplicationBuilder.WebHost zugegriffen 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();

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

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

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

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

app.UseRouting();

// Other middleware and endpoints

app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Mit Ports arbeiten

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 der App festgelegt.

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 reagiert 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.

Port aus den Umgebungsvariablen lesen

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 Umgebungsvariable ASPNETCORE_URLS

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

Auf allen Schnittstellen lauschen

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

An allen Schnittstellen mithilfe von ASPNETCORE_URLS lauschen

Die vorherigen Beispiele können folgendes verwenden ASPNETCORE_URLS:

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

Auf allen Schnittstellen mithilfe von ASPNETCORE_HTTP_PORTS und ASPNETCORE_HTTPS_PORTS lauschen

Die vorherigen Beispiele können auch ASPNETCORE_HTTP_PORTS und ASPNETCORE_HTTPS_PORTS verwenden, aber ASPNETCORE_URLS setzt (wenn festgelegt) die folgenden Einstellungen außer Kraft:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Weitere Informationen finden Sie unter Konfigurieren von Endpunkten für Kestrel webserver.

HTTPS mit Entwicklungszertifikat angeben

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 ASP.NET Core Laufzeitumgebungen.

Configuration

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.

Logging

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 und ASP.NET Core.

Zugreifen auf den Container für Abhängigkeitsinjektion

Der folgende Code zeigt, wie Dienste beim Anwendungsstart aus dem DI-Container abgerufen werden:

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 mithilfe des [FromKeyedServices] Attributs auf Schlüssel aus dem DI-Container zugreifen:

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.Create initialisiert eine neue Instanz der WebApplication-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 Umgebungsvariable und das Befehlszeilenargument, das zum Ändern des Inhaltsstamms, des App-Namens und der Umgebung verwendet wird.

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.

Konfiguration lesen

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

Dienste hinzufügen

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

Passen Sie IHostBuilder an

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

Passen Sie IWebHostBuilder an

Auf die Erweiterungsmethoden von IWebHostBuilder kann über die Eigenschaft WebApplicationBuilder.WebHost zugegriffen 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();

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

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

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

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

app.UseRouting();

// Other middleware and endpoints

app.UseRouting();

app.MapGet("/", () => "hello world");

app.UseEndpoints(e => {});

app.Run(context =>
{
    context.Response.StatusCode = 404;
    return Task.CompletedTask;
});

Mit Ports arbeiten

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 der App festgelegt.

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 reagiert 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.

Port aus den Umgebungsvariablen lesen

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 Umgebungsvariable ASPNETCORE_URLS

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

Auf allen Schnittstellen lauschen

Die folgenden Beispiele veranschaulichen das Lauschen auf 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();

An allen Schnittstellen mithilfe von ASPNETCORE_URLS lauschen

Die vorherigen Beispiele können folgendes verwenden ASPNETCORE_URLS:

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

Auf allen Schnittstellen mithilfe von ASPNETCORE_HTTP_PORTS und ASPNETCORE_HTTPS_PORTS lauschen

Die vorherigen Beispiele können auch ASPNETCORE_HTTP_PORTS und ASPNETCORE_HTTPS_PORTS verwenden, aber ASPNETCORE_URLS setzt (wenn festgelegt) die folgenden Einstellungen außer Kraft:

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Weitere Informationen finden Sie unter Konfigurieren von Endpunkten für Kestrel webserver.

HTTPS mit Entwicklungszertifikat angeben

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 ASP.NET Core Laufzeitumgebungen.

Configuration

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.

Logging

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 und ASP.NET Core.

Zugreifen auf den Container für Abhängigkeitsinjektion

Der folgende Code zeigt, wie Dienste beim Anwendungsstart aus dem DI-Container abgerufen werden:

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 mithilfe des [FromKeyedServices] Attributs auf Schlüssel aus dem DI-Container zugreifen:

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.Create initialisiert eine neue Instanz der WebApplication-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 Umgebungsvariable und das Befehlszeilenargument, das zum Ändern des Inhaltsstamms, des App-Namens und der Umgebung verwendet wird.

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.

Konfiguration lesen

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

Dienste hinzufügen

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

Passen Sie IHostBuilder an

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

Passen Sie IWebHostBuilder an

Auf die Erweiterungsmethoden von IWebHostBuilder kann über die Eigenschaft WebApplicationBuilder.WebHost zugegriffen 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();