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.

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.

Następujący kod uruchamiania aplikacji obsługuje:

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

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

Wstrzykiwanie zależności (usługi)

Platforma ASP.NET Core obejmuje wstrzykiwanie zależności w celu udostępnienia skonfigurowanych usług 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 klasy WebApplicationBuilder dodawanych jest wiele usług udostępnianych przez platformę. 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 powyższym wyróżnionym kodzie element builder posiada konfigurację, funkcje rejestrowania i wiele innych usług dodanych do kontenera wstrzykiwania zależności.

Następujący kod dodaje strony rozwiązania Razor, kontrolery MVC z widokami oraz niestandardową klasę DbContext do kontenera wstrzykiwania zależności:

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

Usługi z kontenera wstrzykiwania zależności są zwykle rozpoznawane przy użyciu wstrzykiwania konstruktora. Struktura wstrzykiwania zależności udostępnia wystąpienie tej usługi w środowisku uruchomieniowym.

W poniższym kodzie wstrzykiwanie konstruktora jest używane do rozpoznania kontekstu bazy danych i rejestratora z poziomu wstrzykiwania zależności:

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

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}. Oprogramowanie pośredniczące dodane do aplikacji zostało wyróżnione w poniższym kodzie:

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

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

ASP.NET Core WebApplication i WebApplicationBuilder typy są zalecane i używane we wszystkich szablonach ASP.NET Core. WebApplication zachowuje się podobnie do hosta ogólnego platformy .NET i uwidacznia wiele tych samych interfejsów, ale wymaga mniej 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 elementu WebApplication:

var builder = WebApplication.CreateBuilder(args);

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

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 ogólnie stosowanych rozszerzeń struktury, takich jak rejestrowanie, wstrzykiwanie zależności, konfiguracja i zarządzanie czasem życia 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. Na platformie ASP.NET Core w wersji 2.0 lub nowszej serwer Kestrel może być uruchamiany 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.

W celu zarządzania poufnymi danymi konfiguracji, takimi jak hasła, dostawcy platformy .NET Core udostępniają menedżera wpisów tajnych. 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:

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

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. Przykład:

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

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

Routing

Trasa to wzorzec adresu URL mapowany na procedurę obsługi. Procedura obsługi to zazwyczaj strona Razor, metoda akcji w kontrolerze MVC lub oprogramowanie pośredniczące. Routing na platformie ASP.NET Core zapewnia kontrolę nad adresami URL używanymi przez aplikację.

Następujący kod generowany przez szablon aplikacji internetowej platformy ASP.NET Core wywołuje metodę UseRouting:

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

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

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.

Zgłaszanie żą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

• Kod źródłowy klasy WebApplicationBuilder