Freigeben über

Übersicht über Grundlagen von ASP.NET Core

Note

Dies ist nicht die neueste Version dieses Artikels. Informationen zum aktuellen Release finden Sie in der .NET 9-Version dieses Artikels.

Warning

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 9-Version dieses Artikels.

Important

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.

Informationen zum aktuellen Release 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.

Informationen zu Blazor wichtigen Anleitungen, die die Anleitungen in diesem Artikel ergänzen oder ersetzen, finden Sie unter ASP.NET CoreBlazor – Grundlagen.

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 wird als eine Reihe von Middleware-Komponenten definiert.

Der folgende App-Startcode unterstützt mehrere App-Typen:

using WebAll.Components;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();
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.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.UseAntiforgery();

app.Run();

Abhängigkeitsinjektion (Dienste)

ASP.NET Core-Funktionen sind in die Abhängigkeitsinjektion (Dependency Injection, DI) integriert, die konfigurierte Dienste innerhalb einer App verfügbar macht. Dienste werden dem DI-Container mit WebApplicationBuilder.Servicesbuilder.Services im vorherigen Code hinzugefügt. Wenn die WebApplicationBuilder instanziert wird, werden viele vom Framework bereitgestellte Dienste automatisch 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 vorhergehenden Code fügt CreateBuilder Konfiguration, Protokollierung und zahlreiche weitere Dienste hinzu. Das DI-Framework stellt während der Laufzeit eine Instanz eines angeforderten Diensts bereit.

Der folgende Code fügt dem DI-Container eine benutzerdefinierte DbContext und Blazor-Komponenten hinzu.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContextFactory<BlazorWebAppMoviesContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("MoviesContext") 
        ?? throw new InvalidOperationException("Connection string not found.")));

builder.Services.AddQuickGridEntityFrameworkAdapter();

builder.Services.AddDatabaseDeveloperPageExceptionFilter();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();

In Blazor Web Apps werden Dienste häufig durch DI während der Laufzeit mithilfe der Anweisung @inject in einer Razor-Komponente aufgelöst, wie im folgenden Beispiel gezeigt:

@page "/movies"
@rendermode InteractiveServer
@using Microsoft.EntityFrameworkCore
@using Microsoft.AspNetCore.Components.QuickGrid
@using BlazorWebAppMovies.Models
@using BlazorWebAppMovies.Data
@implements IAsyncDisposable
@inject IDbContextFactory<BlazorWebAppMovies.Data.BlazorWebAppMoviesContext> DbFactory

<PageTitle>Index</PageTitle>

<h1>Index</h1>

<div>
    <input type="search" @bind="titleFilter" @bind:event="oninput" />
</div>

<p>
    <a href="movies/create">Create New</a>
</p>

<QuickGrid Class="table" Items="FilteredMovies" Pagination="pagination">
    <PropertyColumn Property="movie => movie.Title" Sortable="true" />
    <PropertyColumn Property="movie => movie.ReleaseDate" Title="Release Date" />
    <PropertyColumn Property="movie => movie.Genre" />
    <PropertyColumn Property="movie => movie.Price" />
    <PropertyColumn Property="movie => movie.Rating" />

    <TemplateColumn Context="movie">
        <a href="@($"movies/edit?id={movie.Id}")">Edit</a> |
        <a href="@($"movies/details?id={movie.Id}")">Details</a> |
        <a href="@($"movies/delete?id={movie.Id}")">Delete</a>
    </TemplateColumn>
</QuickGrid>

<Paginator State="pagination" />

@code {
    private BlazorWebAppMoviesContext context = default!;
    private PaginationState pagination = new PaginationState { ItemsPerPage = 10 };
    private string titleFilter = string.Empty;

    private IQueryable<Movie> FilteredMovies =>
        context.Movie.Where(m => m.Title!.Contains(titleFilter));

    protected override void OnInitialized()
    {
        context = DbFactory.CreateDbContext();
    }

    public async ValueTask DisposeAsync() => await context.DisposeAsync();
}

Im obigen Code:

  • Es wird die Anweisung @inject verwendet.
  • Der Dienst wird in der OnInitialized-Methode aufgelöst und der variablen context zugewiesen.
  • Der Dienst context erstellt die Liste FilteredMovie.

Eine weitere Möglichkeit zum Auflösen eines Diensts durch DI ist die Verwendung einer Konstruktorinjektion. Im folgenden Pages-Code Razor 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();
    }
}

Im vorherigen Code verwendet der IndexModel-Konstruktor einen Parameter vom Typ RazorPagesMovieContext, der zur Laufzeit in die _context Variable aufgelöst wird. Das Kontextobjekt wird verwendet, um eine Liste von Filmen in der OnGetAsync-Methode zu erstellen.

Weitere Informationen finden Sie unter ASP.NET Core Blazor– Abhängigkeitsinjektion und 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{Feature}-Erweiterungsmethode hinzugefügt. Die Verwendung von Methoden namens Use{Feature} zum Hinzufügen von Middleware zu einer App wird im folgenden Code veranschaulicht:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContextFactory<BlazorWebAppMoviesContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("MoviesContext") 
        ?? throw new InvalidOperationException("Connection string not found.")));

builder.Services.AddQuickGridEntityFrameworkAdapter();

builder.Services.AddDatabaseDeveloperPageExceptionFilter();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

var app = builder.Build();

using (var scope = app.Services.CreateScope())
{
    var services = scope.ServiceProvider;

    SeedData.Initialize(services);
}

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
    app.UseMigrationsEndPoint();
}
app.UseHttpsRedirection();

app.UseAntiforgery();

app.MapStaticAssets();
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.Run();

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

Host

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

  • eine HTTP-Serverimplementierung
  • Middleware-Komponenten
  • Logging
  • DI-Dienste
  • Configuration

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

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

Im folgenden Beispiel wird ein WebApplication instanziiert und einer Variablen mit dem Namen app zugewiesen:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContextFactory<BlazorWebAppMoviesContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("MoviesContext") 
        ?? throw new InvalidOperationException("Connection string not found.")));

builder.Services.AddQuickGridEntityFrameworkAdapter();

builder.Services.AddDatabaseDeveloperPageExceptionFilter();

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

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 Konfigurationen von appsettings.json, Umgebungsvariablen, Befehlszeilenargumenten und anderen Konfigurationsquellen.
  • Senden von Protokollausgaben an die Konsole und Debuggen von Anbietern.

Nicht-Webszenarien

Der generische Host ermöglicht es anderen Arten von Apps, frameworkübergreifende Erweiterungen zu verwenden, z. B. Protokollierung, Abhängigkeitseinfügung (DI), Konfiguration und Verwaltung der App-Lebensdauer. Weitere Informationen finden Sie unter Generischer .NET-Host in ASP.NET Core und Hintergrundtasks mit gehosteten Diensten in ASP.NET Core.

Servers

Eine ASP.NET Core-App verwendet eine HTTP-Serverimplementierung zum Lauschen auf HTTP-Anforderungen. Der Server stellt Anforderungen an die App als eine Reihe von Anforderungsfeatures dar, die zu einem HttpContext zusammengesetzt werden.

Die folgenden Serverimplementierungen werden von ASP.NET Core bereitgestellt:

  • Kestrel ist ein plattformübergreifender Webserver. Kestrel wird häufig in einer Reverseproxykonfiguration mit 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.

Configuration

ASP.NET Core stellt ein Konfigurationsframework bereit, das Einstellungen als Name-Wert-Paare aus einer sortierten Gruppe 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.

Standardmäßig sind ASP.NET Core-Apps so konfiguriert, dass sie von appsettings.jsonUmgebungsvariablen, der Befehlszeile und mehr gelesen werden. Wenn die Konfiguration der App geladen wird, überschreiben Werte aus Umgebungsvariablen die Werte von appsettings.json.

Zum Verwalten vertraulicher Konfigurationsdaten wie Kennwörter in der Entwicklungsumgebung stellt .NET den geheimen Manager bereit. Für Produktionsgeheimnisse empfehlen wir Azure Key Vault.

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

Environments

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:

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    app.UseHsts();
    app.UseMigrationsEndPoint();
}

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

Logging

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:

  • Console
  • 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. Das folgende Beispiel zeigt, wie Sie eine Protokollierung in einer .razor-Datei für eine Seite in einer Blazor Web App abrufen und verwenden. Ein Protokollierungsobjekt und ein entsprechender Konsolenanbieter werden automatisch im DI-Container gespeichert, wenn die Methode CreateBuilder in Program.cs aufgerufen wird.

@page "/weather"
@attribute [StreamRendering]
@inject ILogger<Weather> Logger

<PageTitle>Weather</PageTitle>

<h1>Weather</h1>

<p>This component demonstrates showing data and logging.</p>

@if (forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th aria-label="Temperature in Celsius">Temp. (C)</th>
                <th aria-label="Temperature in Fahrenheit">Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    private WeatherForecast[]? forecasts;

    protected override async Task OnInitializedAsync()
    {
        // Simulate asynchronous loading to demonstrate streaming rendering
       
        await Task.Delay(500);

        Logger.LogInformation("This is an information log message.");
        Logger.LogWarning("This is a warning log message.");
        Logger.LogError("This is an error log message.");

        var startDate = DateOnly.FromDateTime(DateTime.Now);
        var summaries = new[] { "Freezing", "Bracing", "Chilly",
            "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" };
        forecasts = Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = startDate.AddDays(index),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = summaries[Random.Shared.Next(summaries.Length)]
        }).ToArray();
    }

    private class WeatherForecast
    {
        public DateOnly Date { get; set; }
        public int TemperatureC { get; set; }
        public string? Summary { get; set; }
        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    }
}

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

Routing

Routing in ASP.NET Core ist ein Mechanismus, der eingehende Anforderungen bestimmten Endpunkten in einer Anwendung zuordnet. Sie können URL-Muster definieren, die verschiedenen Komponenten entsprechen, z. B. Blazor Komponenten, Razor Seiten, MVC-Controlleraktionen oder Middleware.

Die Methode UseRouting(IApplicationBuilder) fügt der Anforderungspipeline Routingmiddleware hinzu. Diese Middleware verarbeitet die Routinginformationen und bestimmt den entsprechenden Endpunkt für jede Anforderung. Sie müssen UseRouting nicht explizit aufrufen, es sei denn, Sie möchten die Reihenfolge ändern, in der Middleware verarbeitet wird.

Weitere Informationen finden Sie unter Routing in ASP.NET Core und ASP.NET CoreBlazor – Routing und Navigation.

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.
  • Integriert in Polly, eine beliebte Drittanbieterbibliothek für vorübergehende Fehlerbehandlung.
  • 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.

Inhaltsstamm

Der Inhaltsstamm ist der Basispfad für:

  • Die ausführbare Datei, die die App hosten (.exe).
  • Kompilierte Assemblys, aus denen die App besteht (.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 wwwroot Ordner.

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

Webstamm

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

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

Statische Dateien werden standardmäßig nur aus dem Webstammverzeichnis und dessen Unterverzeichnissen bereitgestellt. Der Webstammpfad ist standardmäßig auf {CONTENT ROOT}/wwwroot festgelegt, wobei der Platzhalter {CONTENT ROOT} der Inhaltsstamm ist. Sie können einen anderen Webstamm festlegen, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie im Webstamm.

Verhindern Sie die Veröffentlichung von Dateien in wwwroot, indem Sie das <Content> Projektelement in der Projektdatei verwenden. Im folgenden Beispiel wird verhindert, dass Inhalte in wwwroot/local und ihren Unterverzeichnissen veröffentlicht werden:

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

In Razor.cshtml-Dateien verweist ~/ auf den Webstamm. Ein Pfad, der beginnt, ~/ wird als virtueller Pfad bezeichnet.

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

Wie man ein Beispiel herunterlädt

Viele der Artikel und Lernprogramme enthalten Links zum Beispielcode.

  1. Laden Sie die zip-Datei des ASP.NET Repositorys herunter.
  2. Entzippen Sie die AspNetCore.Docs-main.zip Datei.
  3. Um auf die Beispiel-App eines Artikels im entzippten Repository zuzugreifen, verwenden Sie die URL im Beispiellink des Artikels, um Sie beim Navigieren zum Ordner des Beispiels zu unterstützen. In der Regel wird oben im Artikel ein Beispiellink mit dem Linktext "Ansicht" oder "Beispielcode herunterladen" angezeigt.

Präprozessordirektiven im Beispielcode

Um mehrere Szenarien zu veranschaulichen, verwenden Beispiel-Apps die #define Direktiven und #if-#else/#elif-#endif Präprozessoren, um verschiedene Abschnitte des Beispielcodes selektiv zu kompilieren und auszuführen. Legen Sie für diese Beispiele, die diesen Ansatz verwenden, die #define Direktive oben in den C#-Dateien fest, um das Dem Szenario zugeordnete Symbol zu definieren, das Sie ausführen möchten. Bei einigen Beispielen muss das Symbol oben in mehreren Dateien definiert werden, um ein Szenario auszuführen.

Die folgende #define Symbolliste gibt beispielsweise an, dass vier Szenarien verfügbar sind (ein Szenario pro Symbol). Die aktuelle Beispielkonfiguration führt das TemplateCode Szenario aus:

#define TemplateCode // or LogFromMain or ExpandDefault or FilterInCode

Um das Beispiel für die Ausführung des ExpandDefault Szenarios zu ändern, definieren Sie das ExpandDefault Symbol, und lassen Sie die verbleibenden Symbole auskommentiert:

#define ExpandDefault // TemplateCode or LogFromMain or FilterInCode

Weitere Informationen zur Verwendung von C#-Präprozessordirektiven zum selektiven Kompilieren von Codeabschnitten finden Sie unter #define (C#-Referenz) und #if (C#-Referenz).

Regionen im Beispielcode

Einige Beispiel-Apps enthalten Codeabschnitte, die von #region - und #endregion C#-Direktiven umgeben sind. Das Dokumentationsbuildsystem fügt diese Regionen in die gerenderten Dokumentationsthemen ein.

Regionsnamen enthalten in der Regel das Wort "Snippet". Das folgende Beispiel zeigt eine Region mit dem Namen snippet_WebHostDefaults.

#region snippet_WebHostDefaults
Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    });
#endregion

Auf den vorherigen C#-Codeausschnitt wird in der Markdowndatei des Themas mit der folgenden Zeile verwiesen:

[!code-csharp[](sample/SampleApp/Program.cs?name=snippet_WebHostDefaults)]

Sie können die Direktiven #region und #endregion, die den Code umgeben, sicher ignorieren oder entfernen. Ändern Sie den Code in diesen Direktiven nicht, wenn Sie die im Thema beschriebenen Beispielszenarien ausführen möchten.

Weitere Informationen finden Sie unter "Mitwirken zur ASP.NET Dokumentation: Codeausschnitte".

Weitere Ressourcen

ASP.NET CoreBlazor – Grundlagen

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 wird als eine Reihe von Middleware-Komponenten 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.Servicesbuilder.Services im vorherigen Code hinzugefügt. Wenn die WebApplicationBuilder Instanziierung erfolgt, 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 Start erstellt eine ASP.NET Core-App einen Host. Der Host kapselt alle Ressourcen der App, zum Beispiel:

  • eine HTTP-Serverimplementierung
  • Middleware-Komponenten
  • Logging
  • DI-Dienste
  • Configuration

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 Konfigurationen von appsettings.json, Umgebungsvariablen, Befehlszeilenargumenten und anderen Konfigurationsquellen.
  • Senden von Protokollausgaben an die Konsole und Debuggen von Anbietern.

Nicht-Webszenarien

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.

Servers

Eine ASP.NET Core-App verwendet eine HTTP-Serverimplementierung zum Lauschen auf HTTP-Anforderungen. Der Server stellt Anforderungen an die App als eine Reihe von Anforderungsfeatures dar, die zu einem HttpContext zusammengesetzt werden.

Die folgenden Serverimplementierungen werden von ASP.NET Core bereitgestellt:

  • Kestrel ist ein plattformübergreifender Webserver. Kestrel wird häufig in einer Reverseproxykonfiguration mit 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.

Configuration

ASP.NET Core stellt ein Konfigurationsframework bereit, das Einstellungen als Name-Wert-Paare aus einer sortierten Gruppe 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.

Standardmäßig sind ASP.NET Core-Apps so konfiguriert, dass sie von appsettings.jsonUmgebungsvariablen, der Befehlszeile und mehr gelesen werden. Wenn die Konfiguration der App geladen wird, überschreiben Werte aus Umgebungsvariablen die Werte von appsettings.json.

Zum Verwalten vertraulicher Konfigurationsdaten wie Kennwörter stellt .NET den geheimen Manager bereit. Für Produktionsgeheimnisse empfehlen wir Azure Key Vault.

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

Environments

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

Logging

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:

  • Console
  • 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 Protokollierung in .NET 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.
  • Integriert in Polly, eine beliebte Drittanbieterbibliothek für vorübergehende Fehlerbehandlung.
  • 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.

Inhaltsstamm

Der Inhaltsstamm ist der Basispfad für:

  • Die ausführbare Datei, die die App hosten (.exe).
  • Kompilierte Assemblys, aus denen die App besteht (.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 sowohl für die Inhaltsdateien der App als auch für den Webstamm. Sie können einen anderen Inhaltsstamm angeben, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie im Inhaltsstamm.

Webstamm

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

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

Statische Dateien werden standardmäßig nur aus dem Webstammverzeichnis und dessen Unterverzeichnissen bereitgestellt. Der Webstammpfad ist standardmäßig auf {content root}/wwwroot festgelegt. Sie können einen anderen Webstamm festlegen, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie im Webstamm.

Verhindern Sie die Veröffentlichung von Dateien in wwwroot mit dem <Projektelement "Inhalt>" in der Projektdatei. Im folgenden Beispiel wird verhindert, dass Inhalte in wwwroot/local und ihren Unterverzeichnissen veröffentlicht werden:

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

In Razor.cshtml-Dateien verweist ~/ auf den Webstamm. Ein Pfad, der beginnt, ~/ 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.

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.

Code zum Konfigurieren (oder Registrieren) von Diensten wird 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 Start erstellt eine ASP.NET Core-App einen Host. Der Host kapselt alle Ressourcen der App, zum Beispiel:

  • eine HTTP-Serverimplementierung
  • Middleware-Komponenten
  • Logging
  • DI-Dienste
  • Configuration

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-Webszenarien

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.

Servers

Eine ASP.NET Core-App verwendet eine HTTP-Serverimplementierung zum Lauschen auf HTTP-Anforderungen. Der Server stellt Anforderungen an die App als eine Reihe von Anforderungsfeatures dar, die zu einem HttpContext zusammengesetzt werden.

Die folgenden Serverimplementierungen werden von ASP.NET Core bereitgestellt:

  • Kestrel ist ein plattformübergreifender Webserver. Kestrel wird häufig in einer Reverseproxykonfiguration mit 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.

Configuration

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.

Standardmäßig sind ASP.NET Core-Apps so konfiguriert, dass sie von appsettings.jsonUmgebungsvariablen, der Befehlszeile und mehr gelesen werden. 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 stellt .NET den geheimen Manager bereit. Für Produktionsgeheimnisse empfehlen wir Azure Key Vault.

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

Environments

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

Logging

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:

  • Console
  • 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 Protokollierung in .NET 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.
  • Integriert in Polly, eine beliebte Drittanbieterbibliothek für vorübergehende Fehlerbehandlung.
  • 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.

Inhaltsstamm

Der Inhaltsstamm ist der Basispfad für:

  • Die ausführbare Datei, die die App hosten (.exe).
  • Kompilierte Assemblys, aus denen die App besteht (.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 sowohl für die Inhaltsdateien der App als auch für den Webstamm. Sie können einen anderen Inhaltsstamm angeben, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie im Inhaltsstamm.

Webstamm

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

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

Statische Dateien werden standardmäßig nur aus dem Webstammverzeichnis und dessen Unterverzeichnissen bereitgestellt. Der Webstammpfad ist standardmäßig auf {content root}/wwwroot festgelegt. Sie können einen anderen Webstamm festlegen, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie im Webstamm.

Verhindern Sie die Veröffentlichung von Dateien in wwwroot mit dem <Projektelement "Inhalt>" in der Projektdatei. Im folgenden Beispiel wird verhindert, dass Inhalte in wwwroot/local und ihren 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 Pfad, der beginnt, ~/ wird als virtueller Pfad bezeichnet.

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

Wie man ein Beispiel herunterlädt

Viele der Artikel und Lernprogramme enthalten Links zum Beispielcode.

  1. Laden Sie die zip-Datei des ASP.NET Repositorys herunter.
  2. Entzippen Sie die AspNetCore.Docs-main.zip Datei.
  3. Um auf die Beispiel-App eines Artikels im entzippten Repository zuzugreifen, verwenden Sie die URL im Beispiellink des Artikels, um Sie beim Navigieren zum Ordner des Beispiels zu unterstützen. In der Regel wird oben im Artikel ein Beispiellink mit dem Linktext "Ansicht" oder "Beispielcode herunterladen" angezeigt.

Präprozessordirektiven im Beispielcode

Um mehrere Szenarien zu veranschaulichen, verwenden Beispiel-Apps die #define Direktiven und #if-#else/#elif-#endif Präprozessoren, um verschiedene Abschnitte des Beispielcodes selektiv zu kompilieren und auszuführen. Legen Sie für diese Beispiele, die diesen Ansatz verwenden, die #define Direktive oben in den C#-Dateien fest, um das Dem Szenario zugeordnete Symbol zu definieren, das Sie ausführen möchten. Bei einigen Beispielen muss das Symbol oben in mehreren Dateien definiert werden, um ein Szenario auszuführen.

Die folgende #define Symbolliste gibt beispielsweise an, dass vier Szenarien verfügbar sind (ein Szenario pro Symbol). Die aktuelle Beispielkonfiguration führt das TemplateCode Szenario aus:

#define TemplateCode // or LogFromMain or ExpandDefault or FilterInCode

Um das Beispiel für die Ausführung des ExpandDefault Szenarios zu ändern, definieren Sie das ExpandDefault Symbol, und lassen Sie die verbleibenden Symbole auskommentiert:

#define ExpandDefault // TemplateCode or LogFromMain or FilterInCode

Weitere Informationen zur Verwendung von C#-Präprozessordirektiven zum selektiven Kompilieren von Codeabschnitten finden Sie unter #define (C#-Referenz) und #if (C#-Referenz).

Regionen im Beispielcode

Einige Beispiel-Apps enthalten Codeabschnitte, die von #region - und #endregion C#-Direktiven umgeben sind. Das Dokumentationsbuildsystem fügt diese Regionen in die gerenderten Dokumentationsthemen ein.

Regionsnamen enthalten in der Regel das Wort "Snippet". Das folgende Beispiel zeigt eine Region mit dem Namen snippet_WebHostDefaults.

#region snippet_WebHostDefaults
Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    });
#endregion

Auf den vorherigen C#-Codeausschnitt wird in der Markdowndatei des Themas mit der folgenden Zeile verwiesen:

[!code-csharp[](sample/SampleApp/Program.cs?name=snippet_WebHostDefaults)]

Sie können die Direktiven #region und #endregion, die den Code umgeben, sicher ignorieren oder entfernen. Ändern Sie den Code in diesen Direktiven nicht, wenn Sie die im Thema beschriebenen Beispielszenarien ausführen möchten.

Weitere Informationen finden Sie unter "Mitwirken zur ASP.NET Dokumentation: Codeausschnitte".

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.

Wichtige Anleitungen zu Blazor, die die Anleitungen in diesem Knoten ergänzen oder ersetzen, finden Sie unter ASP.NET CoreBlazor – Grundlagen.

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 wird als eine Reihe von Middleware-Komponenten 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.Servicesbuilder.Services im vorherigen Code hinzugefügt. Wenn die WebApplicationBuilder Instanziierung erfolgt, 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 Start erstellt eine ASP.NET Core-App einen Host. Der Host kapselt alle Ressourcen der App, zum Beispiel:

  • eine HTTP-Serverimplementierung
  • Middleware-Komponenten
  • Logging
  • DI-Dienste
  • Configuration

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 Konfigurationen von appsettings.json, Umgebungsvariablen, Befehlszeilenargumenten und anderen Konfigurationsquellen.
  • Senden von Protokollausgaben an die Konsole und Debuggen von Anbietern.

Nicht-Webszenarien

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.

Servers

Eine ASP.NET Core-App verwendet eine HTTP-Serverimplementierung zum Lauschen auf HTTP-Anforderungen. Der Server stellt Anforderungen an die App als eine Reihe von Anforderungsfeatures dar, die zu einem HttpContext zusammengesetzt werden.

Die folgenden Serverimplementierungen werden von ASP.NET Core bereitgestellt:

  • Kestrel ist ein plattformübergreifender Webserver. Kestrel wird häufig in einer Reverseproxykonfiguration mit 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.

Configuration

ASP.NET Core stellt ein Konfigurationsframework bereit, das Einstellungen als Name-Wert-Paare aus einer sortierten Gruppe 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.

Standardmäßig sind ASP.NET Core-Apps so konfiguriert, dass sie von appsettings.jsonUmgebungsvariablen, der Befehlszeile und mehr gelesen werden. Wenn die Konfiguration der App geladen wird, überschreiben Werte aus Umgebungsvariablen die Werte von appsettings.json.

Zum Verwalten vertraulicher Konfigurationsdaten wie Kennwörter stellt .NET den geheimen Manager bereit. Für Produktionsgeheimnisse empfehlen wir Azure Key Vault.

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

Environments

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

Logging

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:

  • Console
  • 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 Protokollierung in .NET 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.
  • Integriert in Polly, eine beliebte Drittanbieterbibliothek für vorübergehende Fehlerbehandlung.
  • 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.

Inhaltsstamm

Der Inhaltsstamm ist der Basispfad für:

  • Die ausführbare Datei, die die App hosten (.exe).
  • Kompilierte Assemblys, aus denen die App besteht (.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 sowohl für die Inhaltsdateien der App als auch für den Webstamm. Sie können einen anderen Inhaltsstamm angeben, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie im Inhaltsstamm.

Webstamm

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

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

Statische Dateien werden standardmäßig nur aus dem Webstammverzeichnis und dessen Unterverzeichnissen bereitgestellt. Der Webstammpfad ist standardmäßig auf {content root}/wwwroot festgelegt. Sie können einen anderen Webstamm festlegen, indem Sie den entsprechenden Pfad beim Erstellen des Hosts festlegen. Weitere Informationen finden Sie im Webstamm.

Verhindern Sie die Veröffentlichung von Dateien in wwwroot mit dem <Projektelement "Inhalt>" in der Projektdatei. Im folgenden Beispiel wird verhindert, dass Inhalte in wwwroot/local und ihren Unterverzeichnissen veröffentlicht werden:

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

In Razor.cshtml-Dateien verweist ~/ auf den Webstamm. Ein Pfad, der beginnt, ~/ wird als virtueller Pfad bezeichnet.

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

Wie man ein Beispiel herunterlädt

Viele der Artikel und Lernprogramme enthalten Links zum Beispielcode.

  1. Laden Sie die zip-Datei des ASP.NET Repositorys herunter.
  2. Entzippen Sie die AspNetCore.Docs-main.zip Datei.
  3. Um auf die Beispiel-App eines Artikels im entzippten Repository zuzugreifen, verwenden Sie die URL im Beispiellink des Artikels, um Sie beim Navigieren zum Ordner des Beispiels zu unterstützen. In der Regel wird oben im Artikel ein Beispiellink mit dem Linktext "Ansicht" oder "Beispielcode herunterladen" angezeigt.

Präprozessordirektiven im Beispielcode

Um mehrere Szenarien zu veranschaulichen, verwenden Beispiel-Apps die #define Direktiven und #if-#else/#elif-#endif Präprozessoren, um verschiedene Abschnitte des Beispielcodes selektiv zu kompilieren und auszuführen. Legen Sie für diese Beispiele, die diesen Ansatz verwenden, die #define Direktive oben in den C#-Dateien fest, um das Dem Szenario zugeordnete Symbol zu definieren, das Sie ausführen möchten. Bei einigen Beispielen muss das Symbol oben in mehreren Dateien definiert werden, um ein Szenario auszuführen.

Die folgende #define Symbolliste gibt beispielsweise an, dass vier Szenarien verfügbar sind (ein Szenario pro Symbol). Die aktuelle Beispielkonfiguration führt das TemplateCode Szenario aus:

#define TemplateCode // or LogFromMain or ExpandDefault or FilterInCode

Um das Beispiel für die Ausführung des ExpandDefault Szenarios zu ändern, definieren Sie das ExpandDefault Symbol, und lassen Sie die verbleibenden Symbole auskommentiert:

#define ExpandDefault // TemplateCode or LogFromMain or FilterInCode

Weitere Informationen zur Verwendung von C#-Präprozessordirektiven zum selektiven Kompilieren von Codeabschnitten finden Sie unter #define (C#-Referenz) und #if (C#-Referenz).

Regionen im Beispielcode

Einige Beispiel-Apps enthalten Codeabschnitte, die von #region - und #endregion C#-Direktiven umgeben sind. Das Dokumentationsbuildsystem fügt diese Regionen in die gerenderten Dokumentationsthemen ein.

Regionsnamen enthalten in der Regel das Wort "Snippet". Das folgende Beispiel zeigt eine Region mit dem Namen snippet_WebHostDefaults.

#region snippet_WebHostDefaults
Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseStartup<Startup>();
    });
#endregion

Auf den vorherigen C#-Codeausschnitt wird in der Markdowndatei des Themas mit der folgenden Zeile verwiesen:

[!code-csharp[](sample/SampleApp/Program.cs?name=snippet_WebHostDefaults)]

Sie können die Direktiven #region und #endregion, die den Code umgeben, sicher ignorieren oder entfernen. Ändern Sie den Code in diesen Direktiven nicht, wenn Sie die im Thema beschriebenen Beispielszenarien ausführen möchten.

Weitere Informationen finden Sie unter "Mitwirken zur ASP.NET Dokumentation: Codeausschnitte".