Udostępnij za pośrednictwem

Omówienie podstaw platformy ASP.NET Core

  • Artykuł

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

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ć Blazor podstawowe wskazówki, które dodaje lub zastępuje wskazówki w tym węźle, zobacz ASP.NET Podstawowe Blazor podstawy.

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:

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

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

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.

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. Na 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.

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

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:

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

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

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.

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. Na 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.

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

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.

Klasa Startup

Klasa Startup 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.

Oto przykładowa klasa Startup:

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

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

Wstrzykiwanie zależności (usługi)

Platforma ASP.NET Core obejmuje wbudowaną strukturę wstrzykiwania zależności na potrzeby udostępniania skonfigurowanych usług w całej aplikacji. Przykładową usługą jest składnik rejestrowania.

Kod służący do konfigurowania (lub rejestrowania) usług jest dodawany do metody Startup.ConfigureServices. Na przykład:

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

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

Usługi z kontenera wstrzykiwania zależności są zwykle rozpoznawane przy użyciu wstrzykiwania konstruktora. W przypadku wstrzykiwania konstruktora klasa deklaruje parametr konstruktora wymaganego typu lub interfejs. Struktura wstrzykiwania zależności udostępnia wystąpienie tej usługi w środowisku uruchomieniowym.

W poniższym przykładzie użyto wstrzykiwania konstruktora w celu rozpoznania usługi RazorPagesMovieContext z wstrzykiwania zależności:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;

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

    // ...

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

Jeśli wbudowany kontener IoC nie spełnia wszystkich potrzeb aplikacji, można zamiast tego użyć kontenera IoC innej firmy.

Aby uzyskać więcej informacji, zobacz Wstrzykiwanie zależności na platformie 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... w metodzie Startup.Configure. Aby na przykład włączyć renderowanie plików statycznych, wywołaj metodę UseStaticFiles.

W poniższym przykładzie skonfigurowano potok obsługi żądań:

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

    app.UseRouting();

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

Platforma ASP.NET Core posiada bogaty zestaw wbudowanego oprogramowania pośredniczącego. Można również napisać niestandardowe składniki oprogramowania pośredniczącego.

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ą dwa różne hosty:

  • Host ogólny platformy .NET
  • Host internetowy platformy ASP.NET Core

Zaleca się korzystanie z hosta ogólnego platformy .NET. Host internetowy platformy ASP.NET Core jest dostępny tylko w celu zapewnienia zgodności z poprzednimi wersjami.

W poniższym przykładzie utworzono hosta ogólnego platformy .NET:

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

Metody CreateDefaultBuilder i ConfigureWebHostDefaults konfigurują 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 plików appsettings.json, appsettings.{Environment}.json, zmiennych środowiskowych, argumentów wiersza polecenia i innych źródeł konfiguracji.
  • Wysyłanie danych wyjściowych rejestrowania do konsoli i dostawców debugowania.

Aby uzyskać więcej informacji, zobacz Host ogólny platformy ASP.NET Core.

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.

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.

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.

Preferowanym sposobem odczytywania powiązanych wartości konfiguracji jest użycie wzorca opcji. Aby uzyskać więcej informacji, zobacz Wiązanie hierarchicznych danych konfiguracji przy użyciu wzorca opcji.

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

Środowiska wykonywania, takie jak Development, Staging i Production to pojęcia pierwszej klasy na platformie ASP.NET Core. 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 aplikację, aby dostarczała szczegółowe informacje o błędach w przypadku uruchomienia w środowisku Development:

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

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

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

Metody rejestrowania, takie jak LogInformation obsługują dowolną liczbę pól. Te pola są często używane do konstruowania komunikatu w formacie string, ale niektórzy dostawcy rejestrowania wysyłają je do magazynu danych jako oddzielne pola. Ta funkcja umożliwia dostawcom rejestrowania wdrożenie rejestrowania semantycznego, zwanego również rejestrowaniem strukturalnym.

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ę.

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.

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 tylda i ukośnik (~/) wskazują 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.

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ć Blazor podstawowe wskazówki, które dodaje lub zastępuje wskazówki w tym węźle, zobacz ASP.NET Podstawowe Blazor podstawy.

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:

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

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

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.

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. Na 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.

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