Omówienie podstaw platformy ASP.NET Core

W tym artykule przedstawiono omówienie podstawowych pojęć związanych z tworzeniem aplikacji ASP.NET Core, w tym wstrzykiwania zależności, konfiguracji, oprogramowania pośredniczącego i nie tylko.

Aby uzyskać wskazówki dotyczące podstaw Blazor, które uzupełniają lub zastępują te zawarte w tym artykule, zobacz podstawy ASP.NET Core Blazor.

Program.cs

Aplikacje platformy ASP.NET Core tworzone za pomocą szablonów internetowych zawierają kod uruchamiania aplikacji w pliku Program.cs. Plik Program.cs to miejsce, gdzie:

• Konfigurowane są usługi wymagane przez aplikację.
• Potok obsługiwania żądań aplikacji jest definiowany jako seria składników oprogramowania pośredniczącego.

Poniższy kod uruchamiania aplikacji obsługuje kilka typów aplikacji:

• Blazor Web Apps
• Razor Pages
• Kontrolery MVC z widokami
• Internetowy interfejs API z kontrolerami
• Minimalne internetowe interfejsy API

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

Wstrzykiwanie zależności (usługi)

ASP.NET Core oferuje wbudowane wstrzykiwanie zależności (DI), które udostępnia skonfigurowane usługi w całej aplikacji. Usługi są dodawane do kontenera wstrzykiwania zależności za pomocą właściwości WebApplicationBuilder.Services — builder.Services w powyższym kodzie. Po utworzeniu wystąpienia wiele usług udostępnianych przez platformę są dodawane automatycznie. Element builder w następującym kodzie to klasa WebApplicationBuilder:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

W poprzednim kodzie CreateBuilder dodaje do kontenera DI konfigurację, rejestrowanie i wiele innych usług. Framework DI udostępnia instancję żądanej usługi w czasie działania.

Poniższy kod dodaje niestandardowe składniki DbContext i Blazor do kontenera DI:

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

W Blazor Web Appusługi są często rozwiązywane z DI podczas wykonywania przy użyciu dyrektywy @inject w składniku Razor, jak pokazano w poniższym przykładzie:

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

W poprzednim kodzie:

• Używana jest dyrektywa @inject.
• Usługa jest rozpoznawana w metodzie OnInitialized i przypisana do zmiennej context.
• Usługa context tworzy listę FilteredMovie.

Innym sposobem rozwiązania usługi z di jest użycie iniekcji konstruktora. Poniższy kod Razor Pages używa iniekcji konstruktora do rozwiązywania kontekstu bazy danych i rejestratora z DI.

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

W poprzednim kodzie konstruktor IndexModel przyjmuje parametr typu RazorPagesMovieContext, który jest przypisywany do zmiennej _context w czasie wykonywania. Obiekt kontekstu służy do tworzenia listy filmów w metodzie OnGetAsync.

Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor wstrzykiwanie zależności i Wstrzykiwanie zależności w ASP.NET Core.

Oprogramowanie pośredniczące

Potok obsługi żądań składa się z serii składników oprogramowania pośredniczącego. Każdy składnik wykonuje operacje na właściwości HttpContext i albo wywołuje kolejne oprogramowanie pośredniczące w potoku, albo przerywa żądanie.

Zgodnie z konwencją składnik oprogramowania pośredniczącego jest dodawany do potoku przez wywołanie metody rozszerzenia Use{Feature}. Użycie metod o nazwie Use{Feature} w celu dodania oprogramowania pośredniczącego do aplikacji jest pokazane w następującym kodzie:

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

Aby uzyskać więcej informacji, zobacz Oprogramowanie pośredniczące ASP.NET Core.

Gospodarz

Podczas uruchamiania aplikacja ASP.NET Core tworzy hosta. Host zawiera wszystkie zasoby aplikacji, takie jak:

• Wdrożenia serwera HTTP
• Składniki oprogramowania pośredniczącego
• Rejestrowanie
• Usługi wstrzykiwania zależności
• Konfigurowanie

Istnieją trzy różne hosty, które mogą uruchamiać aplikację ASP.NET Core:

• ASP.NET Core WebApplication, znana również jako minimalny host
• Host ogólny platformy .NET połączony z platformą ASP.NET Core ConfigureWebHostDefaults
• ASP.NET Core WebHost

Zalecane są typy ASP.NET Core WebApplication i WebApplicationBuilder oraz są używane we wszystkich szablonach ASP.NET Core. WebApplication działa podobnie do hosta ogólnego platformy .NET i uwidacznia wiele z tych samych interfejsów, ale wymaga mniejszej liczby wywołań zwrotnych do skonfigurowania. ASP.NET Core WebHost jest dostępny tylko w celu zapewnienia zgodności z poprzednimi wersjami.

Poniższy przykład tworzy wystąpienie WebApplication i przypisuje go do zmiennej o nazwie app:

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

Metoda WebApplicationBuilder.Build konfiguruje hosta z zestawem opcji domyślnych, takich jak:

• Korzystanie z serwera Kestrel jako serwera internetowego i włączenie integracji usług IIS.
• Ładowanie konfiguracji z pliku appsettings.json, zmiennych środowiskowych, argumentów wiersza polecenia i innych źródeł konfiguracji.
• Wysyłanie danych wyjściowych rejestrowania do konsoli i dostawców debugowania.

Scenariusze inne niż internetowe

Host ogólny umożliwia innym typom aplikacji korzystanie z rozszerzeń platform krzyżowych, takich jak rejestrowanie, wstrzykiwanie zależności (DI), konfiguracja i zarządzanie okresem istnienia aplikacji. Aby uzyskać więcej informacji, zobacz Host ogólny platformy .NET Core oraz Zadania w tle z usługami hostowanymi na platformie ASP.NET Core.

Serwery

Aplikacja platformy ASP.NET Core wykorzystuje wdrożenie serwera HTTP do nasłuchiwania żądań HTTP. Serwer przesyła żądania do aplikacji jako zestaw funkcji na żądanie tworzących właściwość HttpContext.

Windows

Platforma ASP. NET Core obsługuje następujące wdrożenia serwera:

• Serwer Kestrel to wieloplatformowy serwer internetowy. Serwer Kestrel jest często uruchamiany w konfiguracji zwrotnego serwera proxy z usługami IIS. W systemie ASP.NET Core 2.0 lub nowszym można uruchomić Kestrel jako publiczny serwer brzegowy uwidoczniony bezpośrednio w Internecie.
• Serwer HTTP usług IIS to serwer systemu Windows wykorzystujący usługi IIS. Na tym serwerze aplikacja ASP.NET Core i usługi IIS są uruchamiane w ramach tego samego procesu.
• Serwer HTTP.sys to serwer systemu Windows, który nie jest używany z usługami IIS.

macOS

Platforma ASP.NET Core udostępnia międzyplatformowe wdrożenia serwera Kestrel. Na platformie ASP.NET Core w wersji 2.0 lub nowszej serwer Kestrel może działać jako publiczny serwer brzegowy uwidoczniony bezpośrednio w Internecie. Serwer Kestrel jest często uruchamiany w konfiguracji zwrotnego serwera proxy z serwerem Nginx lub Apache.

Linux

Platforma ASP.NET Core udostępnia międzyplatformowe wdrożenia serwera Kestrel. Na platformie ASP.NET Core w wersji 2.0 lub nowszej serwer Kestrel może działać jako publiczny serwer brzegowy uwidoczniony bezpośrednio w Internecie. Serwer Kestrel jest często uruchamiany w konfiguracji zwrotnego serwera proxy z serwerem Nginx lub Apache.

Aby uzyskać więcej informacji, zobacz Implementacja serwera internetowego w środowisku ASP.NET Core.

Konfigurowanie

Platforma ASP.NET Core zapewnia strukturę konfiguracji, która pobiera ustawienia w formie par nazwa-wartość z uporządkowanego zestawu dostawców konfiguracji. Wbudowani dostawcy konfiguracji są dostępni dla wielu źródeł, takich jak pliki .json, pliki .xml, zmienne środowiskowe oraz argumenty wiersza polecenia. Można napisać niestandardowych dostawców konfiguracji w celu obsługi innych źródeł.

Aplikacje platformy ASP.NET Core są domyślnieskonfigurowane pod kątem odczytu z pliku appsettings.json, zmiennych środowiskowych, wiersza polecenia i nie tylko. Po załadowaniu konfiguracji aplikacji wartości ze zmiennych środowiskowych zastępują wartości z pliku appsettings.json.

Aby zarządzać poufnymi danymi konfiguracji, takimi jak hasła w środowisku programistycznym, platforma .NET Core udostępnia Secret Manager. W przypadku produkcyjnych wpisów tajnych zalecamy użycie usługi Azure Key Vault.

Aby uzyskać więcej informacji, zobacz Konfiguracja na platformie ASP.NET Core.

Środowiska

Na platformie ASP.NET Core dostępne są środowiska wykonywania, takie jak Development, Staging i Production. Określ środowisko, w którym ma działać aplikacja, ustawiając zmienną środowiskową ASPNETCORE_ENVIRONMENT. Platforma ASP.NET Core odczytuje tę zmienną środowiskową w momencie uruchomienia aplikacji i przechowuje jej wartość we wdrożeniu IWebHostEnvironment. To wdrożenie jest dostępne w dowolnym miejscu aplikacji za pomocą wstrzykiwania zależności.

W poniższym przykładzie skonfigurowano obsługę wyjątków oraz oprogramowanie pośredniczące protokołu HSTS, gdy do uruchamiania nie jest używane środowisko Development:

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

Więcej informacji można znaleźć w temacie Używanie wielu środowisk na platformie ASP.NET Core.

Rejestrowanie

Platforma ASP.NET Core obsługuje interfejs API rejestrowania, który działa z wieloma wbudowanymi dostawcami rejestrowania i dostawcami innych firm. Dostępni są między innymi następujący dostawcy:

• Konsola
• Debugowanie
• Śledzenie zdarzeń w systemie Windows
• Dzienniki zdarzeń systemu Windows
• TraceSource
• Azure App Service
• Azure Application Insights

Aby utworzyć dzienniki, należy rozpoznać usługę ILogger<TCategoryName> z wstrzykiwania zależności i wywołać metody rejestrowania takie jak LogInformation. W poniższym przykładzie pokazano, jak pobrać i użyć rejestratora w pliku .razor dla strony w Blazor Web App. Obiekt rejestratora oraz powiązany z nim dostawca konsoli są automatycznie przechowywane w kontenerze DI, gdy metoda CreateBuilder jest wywoływana w Program.cs.

@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 Farenheit">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);
    }
}

Aby uzyskać więcej informacji, zobacz Rejestrowanie na platformie .NET Core i ASP.NET Core.

Routing

Routing w ASP.NET Core to mechanizm, który mapuje przychodzące żądania do określonych punktów końcowych w aplikacji. Umożliwia definiowanie wzorców adresów URL odpowiadających różnym składnikom, takim jak składniki Blazor, strony Razor, akcje kontrolera MVC lub oprogramowanie pośredniczące.

Metoda UseRouting(IApplicationBuilder) dodaje oprogramowanie pośredniczące routingu do potoku żądania. To oprogramowanie pośredniczące przetwarza informacje o routingu i określa odpowiedni punkt końcowy dla każdego żądania. Nie musisz jawnie wywoływać UseRouting, chyba że chcesz zmienić kolejność przetwarzania oprogramowania pośredniczącego.

Aby uzyskać więcej informacji, zobacz Routing w ASP.NET Core oraz Routing i nawigacja w ASP.NET Core Blazor.

Obsługa błędów

Platforma ASP.NET Core ma wbudowane funkcje obsługi błędów, takie jak:

• Strona wyjątków dla deweloperów
• Niestandardowe strony błędów
• Statyczne strony kodu stanu
• Obsługa wyjątków uruchamiania

Aby uzyskać więcej informacji, zobacz Obsługa błędów na platformie ASP.NET Core.

Tworzenie żądań HTTP

Dostępne jest wdrożenie interfejsu IHttpClientFactory do tworzenia wystąpień HttpClient. Interfejs Factory:

• Zapewnia centralną lokalizację nazewnictwa i konfigurowania wystąpień logicznych HttpClient. Możesz na przykład zarejestrować i skonfigurować klienta usługi github w celu uzyskania dostępu do usługi GitHub. Zarejestruj i skonfiguruj domyślnego klienta do innych celów.
• Obsługuje rejestrację i tworzenie łańcucha wielu procedur obsługi delegowania w celu utworzenia potoku oprogramowania pośredniczącego dla żądań wychodzących. Ten wzorzec jest podobny do potoku oprogramowania pośredniczącego dla ruchu przychodzącego na platformie ASP.NET Core. Ten wzorzec zapewnia mechanizm zarządzania przekrojowymi kwestiami dotyczącymi żądań HTTP, w tym buforowaniem, obsługą błędów, serializacją i rejestrowaniem.
• Integruje się z biblioteką Polly, popularną biblioteką innej firmy na potrzeby obsługi błędów przejściowych.
• Zarządza buforowaniem i cyklem życia podstawowych wystąpień HttpClientHandler w celu uniknięcia typowych problemów serwera DNS występujących podczas ręcznego zarządzania cyklami życia HttpClient.
• Dodaje środowisko rejestrowania z możliwością konfiguracji za pośrednictwem interfejsu ILogger dla wszystkich żądań wysyłanych za pośrednictwem klientów utworzonych przez fabrykę.

Aby uzyskać więcej informacji, zobacz Tworzenie żądań HTTP za pomocą interfejsu IHttpClientFactory na platformie ASP.NET Core.

Katalog główny zawartości

Katalog główny zawartości to ścieżka podstawowa dla:

• Pliku wykonywalnego hostującego aplikację (.exe).
• Skompilowanych zestawów tworzących aplikację (.dll).
• Pliki zawartości używane przez aplikację, takie jak:
  • pliki Razor(.cshtml, .razor);
  • pliki konfiguracji (.json, .xml);
  • pliki danych (.db).
• Internetowego katalogu głównego , którym zwykle jest folder wwwroot.

Podczas programowania katalog główny zawartości domyślnie przyjmuje wartość katalogu głównego projektu. Ten katalog jest również ścieżką podstawową zarówno dla plików zawartości aplikacji, jak i internetowego katalogu głównego. Określ inny katalog główny zawartości, ustawiając ścieżkę podczas tworzenia hosta. Aby uzyskać więcej informacji, zobacz Katalog główny zawartości.

Internetowy katalog główny

Internetowy katalog główny to ścieżka podstawowa w przypadku publicznych, statycznych plików zasobów, takich jak:

• Arkusze stylów (.css)
• JavaScript (.js)
• Obrazy (.png, .jpg)

Domyślnie pliki statyczne są obsługiwane tylko z internetowego katalogu głównego i jego podkatalogów. Ścieżka internetowego katalogu głównego domyślnie przyjmuje wartość {katalog główny zawartości}/wwwroot. Określ inny internetowy katalog główny, ustawiając jego ścieżkę podczas tworzenia hosta. Aby uzyskać więcej informacji, zobacz Internetowy katalog główny.

Aby zapobiec publikowaniu plików w katalogu wwwroot, użyj elementu projektu <Content> w pliku projektu. W następującym przykładzie uniemożliwiono opublikowanie zawartości w katalogu wwwroot/local i jego podkatalogach:

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

W plikach Razor.cshtml znak ~/ wskazuje internetowy katalog główny. Ścieżka rozpoczynająca się od znaku ~/ nazywana jest ścieżką wirtualną.

Aby uzyskać więcej informacji, zobacz Pliki statyczne platformy ASP.NET Core.

Dodatkowe zasoby

• Podstawy BlazorASP.NET Core