Übersicht über Grundlagen von ASP.NET Core

  • Artikel

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Warnung

Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der Supportrichtlinie für .NET und .NET Core. Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.

Wichtig

Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Dieser Artikel bietet eine Übersicht über die grundlegenden Konzepte zum Erstellen von ASP.NET Core-Apps, einschließlich Abhängigkeitsinjektion (Dependency Injection, DI), Konfiguration, Middleware und mehr.

Grundlegende Anleitungen zu Blazor, die den Anleitungen in diesem Knoten ergänzen oder ersetzen, finden Sie unter Grundlagen von ASP.NET Core Blazor.

Program.cs

ASP.NET Core-Apps, die mit den Webvorlagen erstellt wurden, enthalten den Anwendungsstartcode in der Datei Program.cs. Für die Datei Program.cs gilt Folgendes:

  • werden die von der App erforderlichen Dienste konfiguriert.
  • Die Anforderungsverarbeitungspipeline der App ist als eine Reihe von Middlewarekomponenten definiert.

Der nachstehende App-Startcode unterstützt Folgendes:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

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

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Abhängigkeitsinjektion (Dienste)

ASP.NET Core umfasst eine Abhängigkeitsinjektion (Dependency Injection, DI), die konfigurierte Dienste innerhalb einer App verfügbar macht. Dienste werden dem DI-Container mit WebApplicationBuilder.Services hinzugefügt, im vorangegangenen Code builder.Services. Wenn WebApplicationBuilder instanziiert wird, werden viele vom Framework bereitgestellte Dienste hinzugefügt. builder ist im folgenden Code ein WebApplicationBuilder:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

Im vorangehend hervorgehobenen Code wurden dem DI-Container über builder Konfiguration, Protokollierung und viele weitere Dienste hinzugefügt.

Der folgende Code fügt dem DI-Container Razor Pages, MVC-Controller mit Ansichten und einen benutzerdefinierten DbContext hinzu:

using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Data;
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

builder.Services.AddDbContext<RazorPagesMovieContext>(options =>
   options.UseSqlServer(builder.Configuration.GetConnectionString("RPMovieContext")));

var app = builder.Build();

Dienste werden üblicherweise mit einer Constructor Injection aus der DI aufgelöst. Das DI-Framework stellt zur Laufzeit eine Instanz dieses Diensts bereit.

Im folgenden Code wird die Konstruktorinjektion verwendet, um den Datenbankkontext und die Protokollierung aus DI aufzulösen:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

Middleware

Die Pipeline zur Anforderungsverarbeitung besteht aus mehreren Middlewarekomponenten. Jede Komponente führt Vorgänge in einem HttpContext aus und ruft anschließend entweder die nächste Middleware in der Pipeline auf oder beendet die Anforderung.

Gemäß Konvention wird eine Middlewarekomponente der Pipeline durch Aufrufen einer Use{Feature}-Erweiterungsmethode hinzugefügt. Middleware, die der App hinzugefügt wird, wird im folgenden Code hervorgehoben:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

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

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

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

Host

Beim Starten erstellt eine ASP.NET Core-App einen Host. Der Host kapselt alle Ressourcen der App, zum Beispiel:

  • eine HTTP-Serverimplementierung
  • Middlewarekomponenten
  • Protokollierung
  • DI-Dienste
  • Konfiguration

Es gibt drei verschiedene Hosts, die eine ASP.NET Core-App ausführen können:

Die ASP.NET Core-Typen WebApplication und WebApplicationBuilder werden in allen ASP.NET Core-Vorlagen empfohlen und verwendet. WebApplication verhält sich ähnlich wie .NET Generic Host und macht viele gleiche Schnittstellen verfügbar, erfordert jedoch weniger Rückrufe bei der Konfiguration. ASP.NET Core WebHost wird lediglich für die Abwärtskompatibilität zur Verfügung gestellt.

Im folgenden Beispiel wird WebApplication instanziiert:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

Die WebApplicationBuilder.Build-Methode konfiguriert einen Host mit einer Reihe von Standardoptionen, z. B.:

  • Verwenden von Kestrel als Webserver und Aktivieren der Integration der Internetinformationsdienste (IIS).
  • Laden der Konfiguration aus appsettings.json, Umgebungsvariablen, Befehlszeilenargumenten und anderen Konfigurationsquellen.
  • Senden von Protokollausgaben an die Konsole und Debuggen von Anbietern.

Nicht webbasierte Szenarios

Mit dem generischen Host können andere App-Typen querschnittliche Frameworkerweiterungen wie Protokollierung, Dependency Injection (DI), Konfiguration und Lebensdauerverwaltung der App verwenden. Weitere Informationen finden Sie unter Generischer .NET-Host in ASP.NET Core und Hintergrundtasks mit gehosteten Diensten in ASP.NET Core.

Server

Eine ASP.NET Core-App verwendet eine HTTP-Serverimplementierung zum Lauschen auf HTTP-Anforderungen. Der Server sendet Anforderungen an die App in Form von mehreren Anforderungsfunktionen in einem HttpContext.

Die folgenden Serverimplementierungen werden von ASP.NET Core bereitgestellt:

  • Kestrel ist ein plattformübergreifender Webserver. Kestrel wird häufig in einer Reverseproxykonfiguration unter Verwendung der IIS ausgeführt. In ASP.NET Core 2.0 oder höher kann Kestrel als öffentlich zugänglicher Edgeserver ausgeführt werden, der direkt mit dem Internet verbunden ist.
  • Der IIS-HTTP-Server ist ein Server für Windows, der IIS verwendet. Mit diesem Server werden die ASP.NET Core-App und IIS im gleichen Prozess ausgeführt.
  • HTTP.sys ist ein Server für Windows, der nicht mit IIS verwendet wird.

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

Konfiguration

ASP.NET Core bietet ein Konfigurationsframework, das Einstellungen als Name/Wert-Paare aus einer geordneten Menge von Konfigurationsanbietern abruft. Integrierte Konfigurationsanbieter stehen für eine Vielzahl von Quellen zur Verfügung, z. B. für .json-Dateien, .xml-Dateien, Umgebungsvariablen und Befehlszeilenargumente. Schreiben Sie benutzerdefinierte Konfigurationsanbieter, um andere Quellen zu unterstützen.

ASP.NET Core-Apps sind standardmäßig zum Lesen aus appsettings.json, Umgebungsvariablen, der Befehlszeile und mehr konfiguriert. Wenn die Konfiguration der App geladen wird, überschreiben Werte aus Umgebungsvariablen die Werte von appsettings.json.

Zum Verwalten vertraulicher Konfigurationsdaten wie Kennwörter bietet .NET Core den Secret Manager. Für Produktionsgeheimnisse empfehlen wir Azure Key Vault.

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

Umgebungen

In ASP.NET Core stehen Ausführungsumgebungen wie Development, Staging und Production zur Verfügung. Legen Sie die Umgebung fest, in der eine App ausgeführt wird, indem Sie die Umgebungsvariable ASPNETCORE_ENVIRONMENT festlegen. ASP.NET Core liest diese Umgebungsvariable beim Start der App und speichert den Wert in einer IWebHostEnvironment-Implementierung. Diese Implementierung ist per DI überall in einer App verfügbar.

Das folgende Beispiel konfiguriert den Ausnahmehandler und HSTS-Middleware (HTTP Strict Transport Security Protocol), sofern die Ausführung nicht in der Development-Umgebung erfolgt:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

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

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Weitere Informationen finden Sie unter Verwenden mehrerer Umgebungen in ASP.NET Core.

Protokollierung

ASP.NET Core unterstützt eine Protokollierungs-API, die mit einer Vielzahl von integrierten und Drittanbieter-Protokollierungsfunktionen funktioniert. Zu den verfügbaren Anbietern gehören:

  • Konsole
  • Debug
  • Ereignisablaufverfolgung unter Windows
  • Windows-Ereignisprotokoll
  • TraceSource
  • Azure App Service
  • Azure Application Insights

Sie können Protokolle erstellen, indem Sie einen ILogger<TCategoryName>-Dienst aus DI lösen und Protokollierungsmethoden wie LogInformation aufrufen. Beispiel:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

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

Routing

Eine Route ist ein URL-Muster, das einem Handler zugeordnet ist. Der Handler ist normalerweise eine Razor-Seite, eine Aktionsmethode in einem MVC-Controller oder einer Middleware. Mit ASP.NET Core-Routing können Sie steuern, welche URLs von Ihrer App verwendet werden.

Der folgende Code, der von der ASP.NET Core-Webanwendungsvorlage generiert wird, ruft UseRouting auf:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

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

Fehlerbehandlung

ASP.NET Core verfügt über integrierte Funktionen zur Fehlerbehandlung wie beispielsweise:

  • eine Seite mit Ausnahmen für Entwickler
  • Benutzerdefinierte Fehlerseiten
  • statische Statuscodeseiten
  • Fehlerbehandlung während des Starts

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

Übermitteln von HTTP-Anforderungen

Eine Implementierung von IHttpClientFactory ist verfügbar zum Erstellen von HttpClient-Instanzen. Die Factory:

  • Ein zentraler Ort für das Benennen und Konfigurieren logischer HttpClient-Instanzen wird damit geboten. Registrieren und konfigurieren Sie beispielsweise einen GitHub-Client für den Zugriff auf GitHub. Registrieren und konfigurieren Sie einen Standardclient für andere Zwecke.
  • Unterstützt die Registrierung und Verkettung von mehreren delegierenden Handlern, um eine Pipeline für die Middleware für ausgehende Anforderungen zu erstellen. Dieses Muster ähnelt der eingehenden Middlewarepipeline von ASP.NET Core. Das Muster bietet einen Mechanismus zum Verwalten von übergreifenden Belangen für HTTP-Anforderungen, einschließlich der Zwischenspeicherung, Fehlerbehandlung, Serialisierung und Protokollierung.
  • Integrierbar in Polly, eine beliebte Drittanbieter-Bibliothek zur Behandlung vorübergehender Fehler.
  • Das Pooling und die Lebensdauer von zugrunde liegenden HttpClientHandler-Instanzen werden verwaltet, um gängige DNS-Probleme zu vermeiden, die bei der manuellen Verwaltung der HttpClient-Lebensdauer auftreten.
  • Eine konfigurierbare Protokollierungsfunktion wird über ILogger für alle Anforderungen hinzugefügt, die über Clients gesendet werden, die von der Factory erstellt wurden.

Weitere Informationen erhalten Sie unter Stellen von HTTP-Anforderungen mithilfe von IHttpClientFactory in ASP.NET Core.

Inhaltsstammverzeichnis

Der Inhaltsstamm ist der Basispfad für:

  • Die ausführbare Datei, die die App hostet (.exe).
  • Kompilierten Assemblys, die die App bilden (.dll).
  • Inhaltsdateien, die von der App verwendet werden, z. B.:
    • Razor-Dateien (.cshtml, .razor)
    • Konfigurationsdateien (.json, .xml)
    • Datendateien (.db)
  • Der Webstamm, in der Regel der Ordner wwwroot

Während der Entwicklung wird standardmäßig das Stammverzeichnis des Projekts als Inhaltsstamm verwendet. Dieses Verzeichnis ist auch der Basispfad für die Inhaltsdateien der App und den Webstamm. Sie können einen anderen Inhaltsstamm angeben, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie unter Inhaltsstamm.

Webstammverzeichnis

Der Webstamm ist der Basispfad für öffentliche, statische Ressourcendateien, zum Beispiel:

  • Stylesheets (.css)
  • JavaScript (.js)
  • Images (.png, .jpg)

Statische Dateien werden standardmäßig nur aus dem Webstammverzeichnis und dessen Unterverzeichnissen bereitgestellt. Standardmäßig lautet der Webstammpfad {Inhaltsstamm}/wwwroot. Sie können einen anderen Webstamm festlegen, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie unter Webstamm.

Verhindern Sie das Veröffentlichen von Datei in wwwroot über <Inhalt > Projektelement in der Projektdatei. Im folgenden Beispiel wird verhindert, dass Inhalte im Verzeichnis wwwroot/local und dessen Unterverzeichnissen veröffentlicht werden:

<ItemGroup>
  <Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>

In Razor.cshtml-Dateien verweist ~/ auf den Webstamm. Ein mit ~/ beginnender Pfad wird als virtueller Pfad bezeichnet.

Weitere Informationen finden Sie unter Statische Dateien in ASP.NET Core.

Zusätzliche Ressourcen

Dieser Artikel bietet eine Übersicht über die grundlegenden Konzepte zum Erstellen von ASP.NET Core-Apps, einschließlich Abhängigkeitsinjektion (Dependency Injection, DI), Konfiguration, Middleware und mehr.

Program.cs

ASP.NET Core-Apps, die mit den Webvorlagen erstellt wurden, enthalten den Anwendungsstartcode in der Datei Program.cs. Für die Datei Program.cs gilt Folgendes:

  • werden die von der App erforderlichen Dienste konfiguriert.
  • Die Anforderungsverarbeitungspipeline der App ist als eine Reihe von Middlewarekomponenten definiert.

Der nachstehende App-Startcode unterstützt Folgendes:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

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

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Abhängigkeitsinjektion (Dienste)

ASP.NET Core umfasst eine Abhängigkeitsinjektion (Dependency Injection, DI), die konfigurierte Dienste innerhalb einer App verfügbar macht. Dienste werden dem DI-Container mit WebApplicationBuilder.Services hinzugefügt, im vorangegangenen Code builder.Services. Wenn WebApplicationBuilder instanziiert wird, werden viele vom Framework bereitgestellte Dienste hinzugefügt. builder ist im folgenden Code ein WebApplicationBuilder:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

Im vorangehend hervorgehobenen Code wurden dem DI-Container über builder Konfiguration, Protokollierung und viele weitere Dienste hinzugefügt.

Der folgende Code fügt dem DI-Container Razor Pages, MVC-Controller mit Ansichten und einen benutzerdefinierten DbContext hinzu:

using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Data;
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

builder.Services.AddDbContext<RazorPagesMovieContext>(options =>
   options.UseSqlServer(builder.Configuration.GetConnectionString("RPMovieContext")));

var app = builder.Build();

Dienste werden üblicherweise mit einer Constructor Injection aus der DI aufgelöst. Das DI-Framework stellt zur Laufzeit eine Instanz dieses Diensts bereit.

Im folgenden Code wird die Konstruktorinjektion verwendet, um den Datenbankkontext und die Protokollierung aus DI aufzulösen:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

Middleware

Die Pipeline zur Anforderungsverarbeitung besteht aus mehreren Middlewarekomponenten. Jede Komponente führt Vorgänge in einem HttpContext aus und ruft anschließend entweder die nächste Middleware in der Pipeline auf oder beendet die Anforderung.

Gemäß Konvention wird eine Middlewarekomponente der Pipeline durch Aufrufen einer Use{Feature}-Erweiterungsmethode hinzugefügt. Middleware, die der App hinzugefügt wird, wird im folgenden Code hervorgehoben:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

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

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

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

Host

Beim Starten erstellt eine ASP.NET Core-App einen Host. Der Host kapselt alle Ressourcen der App, zum Beispiel:

  • eine HTTP-Serverimplementierung
  • Middlewarekomponenten
  • Protokollierung
  • DI-Dienste
  • Konfiguration

Es gibt drei verschiedene Hosts, die eine ASP.NET Core-App ausführen können:

Die ASP.NET Core-Typen WebApplication und WebApplicationBuilder werden in allen ASP.NET Core-Vorlagen empfohlen und verwendet. WebApplication verhält sich ähnlich wie .NET Generic Host und macht viele gleiche Schnittstellen verfügbar, erfordert jedoch weniger Rückrufe bei der Konfiguration. ASP.NET Core WebHost wird lediglich für die Abwärtskompatibilität zur Verfügung gestellt.

Im folgenden Beispiel wird WebApplication instanziiert:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

Die WebApplicationBuilder.Build-Methode konfiguriert einen Host mit einer Reihe von Standardoptionen, z. B.:

  • Verwenden von Kestrel als Webserver und Aktivieren der Integration der Internetinformationsdienste (IIS).
  • Laden der Konfiguration aus appsettings.json, Umgebungsvariablen, Befehlszeilenargumenten und anderen Konfigurationsquellen.
  • Senden von Protokollausgaben an die Konsole und Debuggen von Anbietern.

Nicht webbasierte Szenarios

Mit dem generischen Host können andere App-Typen querschnittliche Frameworkerweiterungen wie Protokollierung, Dependency Injection (DI), Konfiguration und Lebensdauerverwaltung der App verwenden. Weitere Informationen finden Sie unter Generischer .NET-Host in ASP.NET Core und Hintergrundtasks mit gehosteten Diensten in ASP.NET Core.

Server

Eine ASP.NET Core-App verwendet eine HTTP-Serverimplementierung zum Lauschen auf HTTP-Anforderungen. Der Server sendet Anforderungen an die App in Form von mehreren Anforderungsfunktionen in einem HttpContext.

Die folgenden Serverimplementierungen werden von ASP.NET Core bereitgestellt:

  • Kestrel ist ein plattformübergreifender Webserver. Kestrel wird häufig in einer Reverseproxykonfiguration unter Verwendung der IIS ausgeführt. In ASP.NET Core 2.0 oder höher kann Kestrel als öffentlich zugänglicher Edgeserver ausgeführt werden, der direkt mit dem Internet verbunden ist.
  • Der IIS-HTTP-Server ist ein Server für Windows, der IIS verwendet. Mit diesem Server werden die ASP.NET Core-App und IIS im gleichen Prozess ausgeführt.
  • HTTP.sys ist ein Server für Windows, der nicht mit IIS verwendet wird.

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

Konfiguration

ASP.NET Core bietet ein Konfigurationsframework, das Einstellungen als Name/Wert-Paare aus einer geordneten Menge von Konfigurationsanbietern abruft. Integrierte Konfigurationsanbieter stehen für eine Vielzahl von Quellen zur Verfügung, z. B. für .json-Dateien, .xml-Dateien, Umgebungsvariablen und Befehlszeilenargumente. Schreiben Sie benutzerdefinierte Konfigurationsanbieter, um andere Quellen zu unterstützen.

ASP.NET Core-Apps sind standardmäßig zum Lesen aus appsettings.json, Umgebungsvariablen, der Befehlszeile und mehr konfiguriert. Wenn die Konfiguration der App geladen wird, überschreiben Werte aus Umgebungsvariablen die Werte von appsettings.json.

Zum Verwalten vertraulicher Konfigurationsdaten wie Kennwörter bietet .NET Core den Secret Manager. Für Produktionsgeheimnisse empfehlen wir Azure Key Vault.

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

Umgebungen

In ASP.NET Core stehen Ausführungsumgebungen wie Development, Staging und Production zur Verfügung. Legen Sie die Umgebung fest, in der eine App ausgeführt wird, indem Sie die Umgebungsvariable ASPNETCORE_ENVIRONMENT festlegen. ASP.NET Core liest diese Umgebungsvariable beim Start der App und speichert den Wert in einer IWebHostEnvironment-Implementierung. Diese Implementierung ist per DI überall in einer App verfügbar.

Das folgende Beispiel konfiguriert den Ausnahmehandler und HSTS-Middleware (HTTP Strict Transport Security Protocol), sofern die Ausführung nicht in der Development-Umgebung erfolgt:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

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

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Weitere Informationen finden Sie unter Verwenden mehrerer Umgebungen in ASP.NET Core.

Protokollierung

ASP.NET Core unterstützt eine Protokollierungs-API, die mit einer Vielzahl von integrierten und Drittanbieter-Protokollierungsfunktionen funktioniert. Zu den verfügbaren Anbietern gehören:

  • Konsole
  • Debug
  • Ereignisablaufverfolgung unter Windows
  • Windows-Ereignisprotokoll
  • TraceSource
  • Azure App Service
  • Azure Application Insights

Sie können Protokolle erstellen, indem Sie einen ILogger<TCategoryName>-Dienst aus DI lösen und Protokollierungsmethoden wie LogInformation aufrufen. Beispiel:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

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

Routing

Eine Route ist ein URL-Muster, das einem Handler zugeordnet ist. Der Handler ist normalerweise eine Razor-Seite, eine Aktionsmethode in einem MVC-Controller oder einer Middleware. Mit ASP.NET Core-Routing können Sie steuern, welche URLs von Ihrer App verwendet werden.

Der folgende Code, der von der ASP.NET Core-Webanwendungsvorlage generiert wird, ruft UseRouting auf:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

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

Fehlerbehandlung

ASP.NET Core verfügt über integrierte Funktionen zur Fehlerbehandlung wie beispielsweise:

  • eine Seite mit Ausnahmen für Entwickler
  • Benutzerdefinierte Fehlerseiten
  • statische Statuscodeseiten
  • Fehlerbehandlung während des Starts

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

Übermitteln von HTTP-Anforderungen

Eine Implementierung von IHttpClientFactory ist verfügbar zum Erstellen von HttpClient-Instanzen. Die Factory:

  • Ein zentraler Ort für das Benennen und Konfigurieren logischer HttpClient-Instanzen wird damit geboten. Registrieren und konfigurieren Sie beispielsweise einen GitHub-Client für den Zugriff auf GitHub. Registrieren und konfigurieren Sie einen Standardclient für andere Zwecke.
  • Unterstützt die Registrierung und Verkettung von mehreren delegierenden Handlern, um eine Pipeline für die Middleware für ausgehende Anforderungen zu erstellen. Dieses Muster ähnelt der eingehenden Middlewarepipeline von ASP.NET Core. Das Muster bietet einen Mechanismus zum Verwalten von übergreifenden Belangen für HTTP-Anforderungen, einschließlich der Zwischenspeicherung, Fehlerbehandlung, Serialisierung und Protokollierung.
  • Integrierbar in Polly, eine beliebte Drittanbieter-Bibliothek zur Behandlung vorübergehender Fehler.
  • Das Pooling und die Lebensdauer von zugrunde liegenden HttpClientHandler-Instanzen werden verwaltet, um gängige DNS-Probleme zu vermeiden, die bei der manuellen Verwaltung der HttpClient-Lebensdauer auftreten.
  • Eine konfigurierbare Protokollierungsfunktion wird über ILogger für alle Anforderungen hinzugefügt, die über Clients gesendet werden, die von der Factory erstellt wurden.

Weitere Informationen erhalten Sie unter Stellen von HTTP-Anforderungen mithilfe von IHttpClientFactory in ASP.NET Core.

Inhaltsstammverzeichnis

Der Inhaltsstamm ist der Basispfad für:

  • Die ausführbare Datei, die die App hostet (.exe).
  • Kompilierten Assemblys, die die App bilden (.dll).
  • Inhaltsdateien, die von der App verwendet werden, z. B.:
    • Razor-Dateien (.cshtml, .razor)
    • Konfigurationsdateien (.json, .xml)
    • Datendateien (.db)
  • Der Webstamm, in der Regel der Ordner wwwroot

Während der Entwicklung wird standardmäßig das Stammverzeichnis des Projekts als Inhaltsstamm verwendet. Dieses Verzeichnis ist auch der Basispfad für die Inhaltsdateien der App und den Webstamm. Sie können einen anderen Inhaltsstamm angeben, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie unter Inhaltsstamm.

Webstammverzeichnis

Der Webstamm ist der Basispfad für öffentliche, statische Ressourcendateien, zum Beispiel:

  • Stylesheets (.css)
  • JavaScript (.js)
  • Images (.png, .jpg)

Statische Dateien werden standardmäßig nur aus dem Webstammverzeichnis und dessen Unterverzeichnissen bereitgestellt. Standardmäßig lautet der Webstammpfad {Inhaltsstamm}/wwwroot. Sie können einen anderen Webstamm festlegen, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie unter Webstamm.

Verhindern Sie das Veröffentlichen von Datei in wwwroot über <Inhalt > Projektelement in der Projektdatei. Im folgenden Beispiel wird verhindert, dass Inhalte im Verzeichnis wwwroot/local und dessen Unterverzeichnissen veröffentlicht werden:

<ItemGroup>
  <Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>

In Razor.cshtml-Dateien verweist ~/ auf den Webstamm. Ein mit ~/ beginnender Pfad wird als virtueller Pfad bezeichnet.

Weitere Informationen finden Sie unter Statische Dateien in ASP.NET Core.

Zusätzliche Ressourcen

Dieser Artikel bietet eine Übersicht über die grundlegenden Konzepte zum Erstellen von ASP.NET Core-Apps, einschließlich Abhängigkeitsinjektion (Dependency Injection, DI), Konfiguration, Middleware und mehr.

Die Startup-Klasse

In der Startup-Klasse:

  • werden die von der App erforderlichen Dienste konfiguriert.
  • Die Anforderungsverarbeitungspipeline der App wird mit mehreren Middlewarekomponenten definiert.

Beispiel für eine Startup-Klasse:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddDbContext<RazorPagesMovieContext>(options =>
            options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));

        services.AddControllersWithViews();
        services.AddRazorPages();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapDefaultControllerRoute();
            endpoints.MapRazorPages();
        });
    }
}

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

Abhängigkeitsinjektion (Dienste)

ASP.NET Core umfasst ein integriertes DI-Framework (Dependency Injection), durch das konfigurierte Dienste in einer App bereitgestellt werden. Eine Protokollierungskomponente stellt beispielsweise einen Dienst dar.

wird Code, der Dienste konfiguriert (oder registriert) der Startup.ConfigureServices-Methode hinzugefügt. Beispiel:

public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<RazorPagesMovieContext>(options =>
        options.UseSqlServer(Configuration.GetConnectionString("RazorPagesMovieContext")));

    services.AddControllersWithViews();
    services.AddRazorPages();
}

Dienste werden üblicherweise mit einer Constructor Injection aus der DI aufgelöst. Bei der Constructor Injection deklariert eine Klasse einen Konstruktorparameter des erforderlichen Typs oder einer Schnittstelle. Das DI-Framework stellt zur Laufzeit eine Instanz dieses Diensts bereit.

Im folgenden Beispiel wird die Constructor Injection verwendet, um RazorPagesMovieContext aus der DI zu lösen:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;

    public IndexModel(RazorPagesMovieContext context)
    {
        _context = context;
    }

    // ...

    public async Task OnGetAsync()
    {
        Movies = await _context.Movies.ToListAsync();
    }
}

Wenn der integrierte IoC-Container (Inversion of Control, Steuerungsumkehr) nicht alle Anforderungen einer App erfüllt, kann stattdessen ein IoC-Drittanbietercontainer verwendet werden.

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

Middleware

Die Pipeline zur Anforderungsverarbeitung besteht aus mehreren Middlewarekomponenten. Jede Komponente führt Vorgänge in einem HttpContext aus und ruft anschließend entweder die nächste Middleware in der Pipeline auf oder beendet die Anforderung.

Gemäß Konvention wird eine Middlewarekomponente der Pipeline durch Aufrufen einer Use...-Erweiterungsmethode in der Startup.Configure-Methode hinzugefügt. Um beispielsweise das Rendering statischer Dateien zu aktivieren, rufen Sie UseStaticFiles auf.

Im folgenden Beispiel wird eine Anforderungsverarbeitungspipeline konfiguriert:

public void Configure(IApplicationBuilder app)
{
    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
        endpoints.MapRazorPages();
    });
}

ASP.NET Core enthält zahlreiche integrierte Middlewareanwendungen. Es können auch benutzerdefinierte Middlewarekomponenten geschrieben werden.

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

Host

Beim Starten erstellt eine ASP.NET Core-App einen Host. Der Host kapselt alle Ressourcen der App, zum Beispiel:

  • eine HTTP-Serverimplementierung
  • Middlewarekomponenten
  • Protokollierung
  • DI-Dienste
  • Konfiguration

Es gibt zwei verschiedene Hosts:

  • Generischer .NET-Host
  • ASP.NET Core-Webhost

Der generische .NET-Host wird empfohlen. Der ASP.NET Core-Webhost wird lediglich für die Abwärtskompatibilität zur Verfügung gestellt.

Im folgenden Beispiel wird ein neuer generischer .NET-Host erstellt:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Mit den Methoden CreateDefaultBuilder und ConfigureWebHostDefaults wird ein Host mit mehreren Standardoptionen konfiguriert, zum Beispiel:

  • Verwenden von Kestrel als Webserver und Aktivieren der Integration der Internetinformationsdienste (IIS).
  • Laden der Konfiguration aus appsettings.json, appsettings.{Environment}.json, Umgebungsvariablen, Befehlszeilenargumenten und anderen Konfigurationsquellen.
  • Senden von Protokollausgaben an die Konsole und Debuggen von Anbietern.

Weitere Informationen finden Sie unter Generischer .NET-Host in ASP.NET Core.

Nicht webbasierte Szenarios

Mit dem generischen Host können andere App-Typen querschnittliche Frameworkerweiterungen wie Protokollierung, Dependency Injection (DI), Konfiguration und Lebensdauerverwaltung der App verwenden. Weitere Informationen finden Sie unter Generischer .NET-Host in ASP.NET Core und Hintergrundtasks mit gehosteten Diensten in ASP.NET Core.

Server

Eine ASP.NET Core-App verwendet eine HTTP-Serverimplementierung zum Lauschen auf HTTP-Anforderungen. Der Server sendet Anforderungen an die App in Form von mehreren Anforderungsfunktionen in einem HttpContext.

Die folgenden Serverimplementierungen werden von ASP.NET Core bereitgestellt:

  • Kestrel ist ein plattformübergreifender Webserver. Kestrel wird häufig in einer Reverseproxykonfiguration unter Verwendung der IIS ausgeführt. In ASP.NET Core 2.0 oder höher kann Kestrel als öffentlich zugänglicher Edgeserver ausgeführt werden, der direkt mit dem Internet verbunden ist.
  • Der IIS-HTTP-Server ist ein Server für Windows, der IIS verwendet. Mit diesem Server werden die ASP.NET Core-App und IIS im gleichen Prozess ausgeführt.
  • HTTP.sys ist ein Server für Windows, der nicht mit IIS verwendet wird.

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

Konfiguration

ASP.NET Core bietet ein Konfigurationsframework, das Einstellungen als Name/Wert-Paare aus einer geordneten Menge von Konfigurationsanbietern abruft. Integrierte Konfigurationsanbieter stehen für eine Vielzahl von Quellen zur Verfügung, z. B. für .json-Dateien, .xml-Dateien, Umgebungsvariablen und Befehlszeilenargumente. Schreiben Sie benutzerdefinierte Konfigurationsanbieter, um andere Quellen zu unterstützen.

ASP.NET Core-Apps sind standardmäßig zum Lesen aus appsettings.json, Umgebungsvariablen, der Befehlszeile und mehr konfiguriert. Wenn die Konfiguration der App geladen wird, überschreiben Werte aus Umgebungsvariablen die Werte von appsettings.json.

Die bevorzugte Methode für das Lesen zugehöriger Konfigurationswerte ist die Verwendung des Optionsmusters. Weitere Informationen finden Sie unter Binden hierarchischer Konfigurationsdaten mit dem Optionsmuster.

Zum Verwalten vertraulicher Konfigurationsdaten wie Kennwörter bietet .NET Core den Secret Manager. Für Produktionsgeheimnisse empfehlen wir Azure Key Vault.

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

Umgebungen

Ausführungsumgebungen wie Development, Staging und Production sind in ASP.NET Core von besonderer Bedeutung. Legen Sie die Umgebung fest, in der eine App ausgeführt wird, indem Sie die Umgebungsvariable ASPNETCORE_ENVIRONMENT festlegen. ASP.NET Core liest diese Umgebungsvariable beim Start der App und speichert den Wert in einer IWebHostEnvironment-Implementierung. Diese Implementierung ist per DI überall in einer App verfügbar.

Im Folgenden Beispiel wird die App so konfiguriert, dass sie ausführliche Fehlerinformationen angibt, wenn sie in der Development-Umgebung ausgeführt wird:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapDefaultControllerRoute();
        endpoints.MapRazorPages();
    });
}

Weitere Informationen finden Sie unter Verwenden mehrerer Umgebungen in ASP.NET Core.

Protokollierung

ASP.NET Core unterstützt eine Protokollierungs-API, die mit einer Vielzahl von integrierten und Drittanbieter-Protokollierungsfunktionen funktioniert. Zu den verfügbaren Anbietern gehören:

  • Konsole
  • Debug
  • Ereignisablaufverfolgung unter Windows
  • Windows-Ereignisprotokoll
  • TraceSource
  • Azure App Service
  • Azure Application Insights

Sie können Protokolle erstellen, indem Sie einen ILogger<TCategoryName>-Dienst aus DI lösen und Protokollierungsmethoden wie LogInformation aufrufen. Beispiel:

public class TodoController : ControllerBase
{
    private readonly ILogger _logger;

    public TodoController(ILogger<TodoController> logger)
    {
        _logger = logger;
    }

    [HttpGet("{id}", Name = "GetTodo")]
    public ActionResult<TodoItem> GetById(string id)
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {Id}", id);
        
        // Item lookup code removed.
        
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({Id}) NOT FOUND", id);
            return NotFound();
        }
        
        return item;
    }
}

Protokollierungsmethoden wie LogInformation unterstützen eine beliebige Anzahl von Feldern. Diese Felder werden häufig zum Erstellen einer string-Meldung verwendet, einige Protokollierungsanbieter senden sie jedoch als separate Felder an einen Datenspeicher. Dieses Funktion ermöglicht Protokollierungsanbietern das Implementieren von semantischer Protokollierung, auch bezeichnet als strukturierte Protokollierung.

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

Routing

Eine Route ist ein URL-Muster, das einem Handler zugeordnet ist. Der Handler ist normalerweise eine Razor-Seite, eine Aktionsmethode in einem MVC-Controller oder einer Middleware. Mit ASP.NET Core-Routing können Sie steuern, welche URLs von Ihrer App verwendet werden.

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

Fehlerbehandlung

ASP.NET Core verfügt über integrierte Funktionen zur Fehlerbehandlung wie beispielsweise:

  • eine Seite mit Ausnahmen für Entwickler
  • Benutzerdefinierte Fehlerseiten
  • statische Statuscodeseiten
  • Fehlerbehandlung während des Starts

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

Übermitteln von HTTP-Anforderungen

Eine Implementierung von IHttpClientFactory ist verfügbar zum Erstellen von HttpClient-Instanzen. Die Factory:

  • Ein zentraler Ort für das Benennen und Konfigurieren logischer HttpClient-Instanzen wird damit geboten. Registrieren und konfigurieren Sie beispielsweise einen GitHub-Client für den Zugriff auf GitHub. Registrieren und konfigurieren Sie einen Standardclient für andere Zwecke.
  • Unterstützt die Registrierung und Verkettung von mehreren delegierenden Handlern, um eine Pipeline für die Middleware für ausgehende Anforderungen zu erstellen. Dieses Muster ähnelt der eingehenden Middlewarepipeline von ASP.NET Core. Das Muster bietet einen Mechanismus zum Verwalten von übergreifenden Belangen für HTTP-Anforderungen, einschließlich der Zwischenspeicherung, Fehlerbehandlung, Serialisierung und Protokollierung.
  • Integrierbar in Polly, eine beliebte Drittanbieter-Bibliothek zur Behandlung vorübergehender Fehler.
  • Das Pooling und die Lebensdauer von zugrunde liegenden HttpClientHandler-Instanzen werden verwaltet, um gängige DNS-Probleme zu vermeiden, die bei der manuellen Verwaltung der HttpClient-Lebensdauer auftreten.
  • Eine konfigurierbare Protokollierungsfunktion wird über ILogger für alle Anforderungen hinzugefügt, die über Clients gesendet werden, die von der Factory erstellt wurden.

Weitere Informationen erhalten Sie unter Stellen von HTTP-Anforderungen mithilfe von IHttpClientFactory in ASP.NET Core.

Inhaltsstammverzeichnis

Der Inhaltsstamm ist der Basispfad für:

  • Die ausführbare Datei, die die App hostet (.exe).
  • Kompilierten Assemblys, die die App bilden (.dll).
  • Inhaltsdateien, die von der App verwendet werden, z. B.:
    • Razor-Dateien (.cshtml, .razor)
    • Konfigurationsdateien (.json, .xml)
    • Datendateien (.db)
  • Der Webstamm, in der Regel der Ordner wwwroot

Während der Entwicklung wird standardmäßig das Stammverzeichnis des Projekts als Inhaltsstamm verwendet. Dieses Verzeichnis ist auch der Basispfad für die Inhaltsdateien der App und den Webstamm. Sie können einen anderen Inhaltsstamm angeben, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie unter Inhaltsstamm.

Webstammverzeichnis

Der Webstamm ist der Basispfad für öffentliche, statische Ressourcendateien, zum Beispiel:

  • Stylesheets (.css)
  • JavaScript (.js)
  • Images (.png, .jpg)

Statische Dateien werden standardmäßig nur aus dem Webstammverzeichnis und dessen Unterverzeichnissen bereitgestellt. Standardmäßig lautet der Webstammpfad {Inhaltsstamm}/wwwroot. Sie können einen anderen Webstamm festlegen, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie unter Webstamm.

Verhindern Sie das Veröffentlichen von Datei in wwwroot über <Inhalt > Projektelement in der Projektdatei. Im folgenden Beispiel wird verhindert, dass Inhalte im Verzeichnis wwwroot/local und dessen Unterverzeichnissen veröffentlicht werden:

<ItemGroup>
  <Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>

In Razor.cshtml-Dateien verweisen Tilde und Schrägstrich (~/) auf den Webstamm. Ein mit ~/ beginnender Pfad wird als virtueller Pfad bezeichnet.

Weitere Informationen finden Sie unter Statische Dateien in ASP.NET Core.

Dieser Artikel bietet eine Übersicht über die grundlegenden Konzepte zum Erstellen von ASP.NET Core-Apps, einschließlich Abhängigkeitsinjektion (Dependency Injection, DI), Konfiguration, Middleware und mehr.

Grundlegende Anleitungen zu Blazor, die den Anleitungen in diesem Knoten ergänzen oder ersetzen, finden Sie unter Grundlagen von ASP.NET Core Blazor.

Program.cs

ASP.NET Core-Apps, die mit den Webvorlagen erstellt wurden, enthalten den Anwendungsstartcode in der Datei Program.cs. Für die Datei Program.cs gilt Folgendes:

  • werden die von der App erforderlichen Dienste konfiguriert.
  • Die Anforderungsverarbeitungspipeline der App ist als eine Reihe von Middlewarekomponenten definiert.

Der nachstehende App-Startcode unterstützt Folgendes:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

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

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Abhängigkeitsinjektion (Dienste)

ASP.NET Core umfasst eine Abhängigkeitsinjektion (Dependency Injection, DI), die konfigurierte Dienste innerhalb einer App verfügbar macht. Dienste werden dem DI-Container mit WebApplicationBuilder.Services hinzugefügt, im vorangegangenen Code builder.Services. Wenn WebApplicationBuilder instanziiert wird, werden viele vom Framework bereitgestellte Dienste hinzugefügt. builder ist im folgenden Code ein WebApplicationBuilder:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

Im vorangehend hervorgehobenen Code wurden dem DI-Container über builder Konfiguration, Protokollierung und viele weitere Dienste hinzugefügt.

Der folgende Code fügt dem DI-Container Razor Pages, MVC-Controller mit Ansichten und einen benutzerdefinierten DbContext hinzu:

using Microsoft.EntityFrameworkCore;
using RazorPagesMovie.Data;
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

builder.Services.AddDbContext<RazorPagesMovieContext>(options =>
   options.UseSqlServer(builder.Configuration.GetConnectionString("RPMovieContext")));

var app = builder.Build();

Dienste werden üblicherweise mit einer Constructor Injection aus der DI aufgelöst. Das DI-Framework stellt zur Laufzeit eine Instanz dieses Diensts bereit.

Im folgenden Code wird die Konstruktorinjektion verwendet, um den Datenbankkontext und die Protokollierung aus DI aufzulösen:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

Middleware

Die Pipeline zur Anforderungsverarbeitung besteht aus mehreren Middlewarekomponenten. Jede Komponente führt Vorgänge in einem HttpContext aus und ruft anschließend entweder die nächste Middleware in der Pipeline auf oder beendet die Anforderung.

Gemäß Konvention wird eine Middlewarekomponente der Pipeline durch Aufrufen einer Use{Feature}-Erweiterungsmethode hinzugefügt. Middleware, die der App hinzugefügt wird, wird im folgenden Code hervorgehoben:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

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

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

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

Host

Beim Starten erstellt eine ASP.NET Core-App einen Host. Der Host kapselt alle Ressourcen der App, zum Beispiel:

  • eine HTTP-Serverimplementierung
  • Middlewarekomponenten
  • Protokollierung
  • DI-Dienste
  • Konfiguration

Es gibt drei verschiedene Hosts, die eine ASP.NET Core-App ausführen können:

Die ASP.NET Core-Typen WebApplication und WebApplicationBuilder werden in allen ASP.NET Core-Vorlagen empfohlen und verwendet. WebApplication verhält sich ähnlich wie .NET Generic Host und macht viele gleiche Schnittstellen verfügbar, erfordert jedoch weniger Rückrufe bei der Konfiguration. ASP.NET Core WebHost wird lediglich für die Abwärtskompatibilität zur Verfügung gestellt.

Im folgenden Beispiel wird WebApplication instanziiert:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

Die WebApplicationBuilder.Build-Methode konfiguriert einen Host mit einer Reihe von Standardoptionen, z. B.:

  • Verwenden von Kestrel als Webserver und Aktivieren der Integration der Internetinformationsdienste (IIS).
  • Laden der Konfiguration aus appsettings.json, Umgebungsvariablen, Befehlszeilenargumenten und anderen Konfigurationsquellen.
  • Senden von Protokollausgaben an die Konsole und Debuggen von Anbietern.

Nicht webbasierte Szenarios

Mit dem generischen Host können andere App-Typen querschnittliche Frameworkerweiterungen wie Protokollierung, Dependency Injection (DI), Konfiguration und Lebensdauerverwaltung der App verwenden. Weitere Informationen finden Sie unter Generischer .NET-Host in ASP.NET Core und Hintergrundtasks mit gehosteten Diensten in ASP.NET Core.

Server

Eine ASP.NET Core-App verwendet eine HTTP-Serverimplementierung zum Lauschen auf HTTP-Anforderungen. Der Server sendet Anforderungen an die App in Form von mehreren Anforderungsfunktionen in einem HttpContext.

Die folgenden Serverimplementierungen werden von ASP.NET Core bereitgestellt:

  • Kestrel ist ein plattformübergreifender Webserver. Kestrel wird häufig in einer Reverseproxykonfiguration unter Verwendung der IIS ausgeführt. In ASP.NET Core 2.0 oder höher kann Kestrel als öffentlich zugänglicher Edgeserver ausgeführt werden, der direkt mit dem Internet verbunden ist.
  • Der IIS-HTTP-Server ist ein Server für Windows, der IIS verwendet. Mit diesem Server werden die ASP.NET Core-App und IIS im gleichen Prozess ausgeführt.
  • HTTP.sys ist ein Server für Windows, der nicht mit IIS verwendet wird.

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

Konfiguration

ASP.NET Core bietet ein Konfigurationsframework, das Einstellungen als Name/Wert-Paare aus einer geordneten Menge von Konfigurationsanbietern abruft. Integrierte Konfigurationsanbieter stehen für eine Vielzahl von Quellen zur Verfügung, z. B. für .json-Dateien, .xml-Dateien, Umgebungsvariablen und Befehlszeilenargumente. Schreiben Sie benutzerdefinierte Konfigurationsanbieter, um andere Quellen zu unterstützen.

ASP.NET Core-Apps sind standardmäßig zum Lesen aus appsettings.json, Umgebungsvariablen, der Befehlszeile und mehr konfiguriert. Wenn die Konfiguration der App geladen wird, überschreiben Werte aus Umgebungsvariablen die Werte von appsettings.json.

Zum Verwalten vertraulicher Konfigurationsdaten wie Kennwörter bietet .NET Core den Secret Manager. Für Produktionsgeheimnisse empfehlen wir Azure Key Vault.

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

Umgebungen

In ASP.NET Core stehen Ausführungsumgebungen wie Development, Staging und Production zur Verfügung. Legen Sie die Umgebung fest, in der eine App ausgeführt wird, indem Sie die Umgebungsvariable ASPNETCORE_ENVIRONMENT festlegen. ASP.NET Core liest diese Umgebungsvariable beim Start der App und speichert den Wert in einer IWebHostEnvironment-Implementierung. Diese Implementierung ist per DI überall in einer App verfügbar.

Das folgende Beispiel konfiguriert den Ausnahmehandler und HSTS-Middleware (HTTP Strict Transport Security Protocol), sofern die Ausführung nicht in der Development-Umgebung erfolgt:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddControllersWithViews();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

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

app.MapDefaultControllerRoute();
app.MapRazorPages();

app.Run();

Weitere Informationen finden Sie unter Verwenden mehrerer Umgebungen in ASP.NET Core.

Protokollierung

ASP.NET Core unterstützt eine Protokollierungs-API, die mit einer Vielzahl von integrierten und Drittanbieter-Protokollierungsfunktionen funktioniert. Zu den verfügbaren Anbietern gehören:

  • Konsole
  • Debug
  • Ereignisablaufverfolgung unter Windows
  • Windows-Ereignisprotokoll
  • TraceSource
  • Azure App Service
  • Azure Application Insights

Sie können Protokolle erstellen, indem Sie einen ILogger<TCategoryName>-Dienst aus DI lösen und Protokollierungsmethoden wie LogInformation aufrufen. Beispiel:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;
    private readonly ILogger<IndexModel> _logger;

    public IndexModel(RazorPagesMovieContext context, ILogger<IndexModel> logger)
    {
        _context = context;
        _logger = logger;
    }

    public IList<Movie> Movie { get;set; }

    public async Task OnGetAsync()
    {
        _logger.LogInformation("IndexModel OnGetAsync.");
        Movie = await _context.Movie.ToListAsync();
    }
}

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

Routing

Eine Route ist ein URL-Muster, das einem Handler zugeordnet ist. Der Handler ist normalerweise eine Razor-Seite, eine Aktionsmethode in einem MVC-Controller oder einer Middleware. Mit ASP.NET Core-Routing können Sie steuern, welche URLs von Ihrer App verwendet werden.

Der folgende Code, der von der ASP.NET Core-Webanwendungsvorlage generiert wird, ruft UseRouting auf:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

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

Fehlerbehandlung

ASP.NET Core verfügt über integrierte Funktionen zur Fehlerbehandlung wie beispielsweise:

  • eine Seite mit Ausnahmen für Entwickler
  • Benutzerdefinierte Fehlerseiten
  • statische Statuscodeseiten
  • Fehlerbehandlung während des Starts

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

Übermitteln von HTTP-Anforderungen

Eine Implementierung von IHttpClientFactory ist verfügbar zum Erstellen von HttpClient-Instanzen. Die Factory:

  • Ein zentraler Ort für das Benennen und Konfigurieren logischer HttpClient-Instanzen wird damit geboten. Registrieren und konfigurieren Sie beispielsweise einen GitHub-Client für den Zugriff auf GitHub. Registrieren und konfigurieren Sie einen Standardclient für andere Zwecke.
  • Unterstützt die Registrierung und Verkettung von mehreren delegierenden Handlern, um eine Pipeline für die Middleware für ausgehende Anforderungen zu erstellen. Dieses Muster ähnelt der eingehenden Middlewarepipeline von ASP.NET Core. Das Muster bietet einen Mechanismus zum Verwalten von übergreifenden Belangen für HTTP-Anforderungen, einschließlich der Zwischenspeicherung, Fehlerbehandlung, Serialisierung und Protokollierung.
  • Integrierbar in Polly, eine beliebte Drittanbieter-Bibliothek zur Behandlung vorübergehender Fehler.
  • Das Pooling und die Lebensdauer von zugrunde liegenden HttpClientHandler-Instanzen werden verwaltet, um gängige DNS-Probleme zu vermeiden, die bei der manuellen Verwaltung der HttpClient-Lebensdauer auftreten.
  • Eine konfigurierbare Protokollierungsfunktion wird über ILogger für alle Anforderungen hinzugefügt, die über Clients gesendet werden, die von der Factory erstellt wurden.

Weitere Informationen erhalten Sie unter Stellen von HTTP-Anforderungen mithilfe von IHttpClientFactory in ASP.NET Core.

Inhaltsstammverzeichnis

Der Inhaltsstamm ist der Basispfad für:

  • Die ausführbare Datei, die die App hostet (.exe).
  • Kompilierten Assemblys, die die App bilden (.dll).
  • Inhaltsdateien, die von der App verwendet werden, z. B.:
    • Razor-Dateien (.cshtml, .razor)
    • Konfigurationsdateien (.json, .xml)
    • Datendateien (.db)
  • Der Webstamm, in der Regel der Ordner wwwroot

Während der Entwicklung wird standardmäßig das Stammverzeichnis des Projekts als Inhaltsstamm verwendet. Dieses Verzeichnis ist auch der Basispfad für die Inhaltsdateien der App und den Webstamm. Sie können einen anderen Inhaltsstamm angeben, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie unter Inhaltsstamm.

Webstammverzeichnis

Der Webstamm ist der Basispfad für öffentliche, statische Ressourcendateien, zum Beispiel:

  • Stylesheets (.css)
  • JavaScript (.js)
  • Images (.png, .jpg)

Statische Dateien werden standardmäßig nur aus dem Webstammverzeichnis und dessen Unterverzeichnissen bereitgestellt. Standardmäßig lautet der Webstammpfad {Inhaltsstamm}/wwwroot. Sie können einen anderen Webstamm festlegen, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie unter Webstamm.

Verhindern Sie das Veröffentlichen von Datei in wwwroot über <Inhalt > Projektelement in der Projektdatei. Im folgenden Beispiel wird verhindert, dass Inhalte im Verzeichnis wwwroot/local und dessen Unterverzeichnissen veröffentlicht werden:

<ItemGroup>
  <Content Update="wwwroot\local\**\*.*" CopyToPublishDirectory="Never" />
</ItemGroup>

In Razor.cshtml-Dateien verweist ~/ auf den Webstamm. Ein mit ~/ beginnender Pfad wird als virtueller Pfad bezeichnet.

Weitere Informationen finden Sie unter Statische Dateien in ASP.NET Core.

Zusätzliche Ressourcen