Übersicht über Grundlagen von 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:

• Razor Pages
• MVC-Controller mit Ansichten
• Web-APIs mit Controllern
• Minimale Web-APIs

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:

• ASP.NET Core WebApplication, auch bekannt als minimaler Host.
• .NET Generic Host in Kombination mit ASP.NET Core ConfigureWebHostDefaults
• ASP.NET Core WebHost

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.

Windows

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.

macOS

ASP.NET Core bietet die plattformübergreifende Serverimplementierung von Kestrel. 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. Kestrel wird häufig in einer Reverseproxykonfiguration mit Nginx oder Apache ausgeführt.

Linux

ASP.NET Core bietet die plattformübergreifende Serverimplementierung von Kestrel. 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. Kestrel wird häufig in einer Reverseproxykonfiguration mit Nginx oder Apache ausgeführt.

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

• WebApplicationBuilder-Quellcode