Přehled základů ASP.NET Core

Tento článek obsahuje přehled základních informací o vytváření aplikací ASP.NET Core, včetně injektáže závislostí (DI), konfigurace, middlewaru a dalších.

Pro pokyny k základům pro Blazor, které doplňují nebo nahrazují pokyny v tomto článku, se podívejte na ASP.NET Core Blazor základy.

Program.cs

Aplikace ASP.NET Core vytvořené pomocí webových šablon obsahují spouštěcí kód aplikace v souboru Program.cs. Soubor Program.cs je tam, kde:

• Jsou nakonfigurovány služby vyžadované aplikací.
• Je definován kanál zpracování požadavků aplikace jako řada komponent middlewaru.

Následující spouštěcí kód aplikace podporuje několik typů aplikací:

• Blazor Web Apps
• Razor Pages
• Kontrolery MVC se zobrazeními
• Webové rozhraní API s kontrolery
• Minimální webová rozhraní 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();

Injektáž závislostí (služby)

ASP.NET základní funkce integrované injektáže závislostí (DI), které zpřístupňuje nakonfigurované služby v celé aplikaci. Služby se přidají do kontejneru DI pomocí třídy WebApplicationBuilder.Services, v předchozím kódu builder.Services. Po vytvoření instance WebApplicationBuilder se automaticky přidá mnoho služeb poskytovaných architekturou ,. builder je v následující kódu WebApplicationBuilder:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

V předchozím kódu CreateBuilder přidá do kontejneru DI konfiguraci, protokolování a mnoho dalších služeb. Rozhraní DI poskytuje instanci požadované služby za běhu.

Následující kód přidá do kontejneru DI vlastní DbContext a Blazor komponenty:

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

V Blazor Web Apps se služby často získávají z DI za běhu pomocí direktivy @inject v komponentě Razor, jak je znázorněno v následujícím příkladu:

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

V předchozím kódu:

• Používá se direktiva @inject.
• Služba se vyřeší metodou OnInitialized a přiřadí se proměnné context.
• Služba context vytvoří seznam FilteredMovie.

Dalším způsobem vyřešení služby pomocí DI je použití konstruktorové injektáže. Následující kód Razor Pages používá injektáž konstruktoru pro vyřešení kontextu databáze a loggeru 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();
    }
}

V předchozím kódu konstruktor IndexModel přebírá parametr typu RazorPagesMovieContext, který je vyřešen v době běhu do proměnné _context. Kontextový objekt slouží k vytvoření seznamu filmů v metodě OnGetAsync.

Další informace najdete v tématu injektáž závislosti v ASP.NET Core Blazor a injektáž závislosti v ASP.NET Core .

Middleware

Kanál zpracování požadavků se skládá z řady komponent middlewaru. Každá komponenta provádí operace v kontextu HttpContext a buď vyvolá další middleware v kanálu, nebo požadavek ukončí.

Podle konvence se do kanálu přidá komponenta middlewaru vyvoláním metody rozšíření Use{Feature}. Použití metod pojmenovaných Use{Feature} k přidání middlewaru do aplikace je znázorněno v následujícím kódu:

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

Další informace najdete v tématu Middleware ASP.NET Core.

Hostitelský počítač

Při spuštění vytvoří aplikace ASP.NET Core hostitele. Hostitel zapouzdřuje všechny prostředky aplikace, například:

• Implementace serveru HTTP
• Komponenty middlewaru
• Protokolování
• Služby injektáže závislostí (DI)
• Konfigurace

Existují tři různí hostitelé, kteří můžou spustit aplikaci ASP.NET Core:

• ASP.NET Core WebApplication, označované také jako minimální hostitel
• Obecný hostitel .NET v kombinaci s ASP.NET Core ConfigureWebHostDefaults
• ASP.NET Core WebHost

Typy ASP.NET Core WebApplication a WebApplicationBuilder jsou doporučovány a používají se ve všech šablonách ASP.NET Core. WebApplication se chová podobně jako obecný hostitel .NET a zpřístupňuje mnoho stejných rozhraní, ale ke konfiguraci vyžaduje méně zpětných volání. ASP.NET Core WebHost je k dispozici pouze pro zpětnou kompatibilitu.

Následující příklad vytvoří instanci WebApplication a přiřadí ji proměnné s názvem 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 nakonfiguruje hostitele pomocí sady výchozích možností, například:

• Použít Kestrel jako webový server a povolit integraci služby IIS
• Načíst konfiguraci ze souboru appsettings.json, proměnných prostředí, argumentů příkazového řádku a dalších zdrojů konfigurace
• Odeslat výstup protokolování do konzoly a poskytovatelům ladění

Newebové scénáře

Obecný hostitel umožňuje jiným typům aplikací používat průřezová rozšíření architektury, jako je logování, vkládání závislostí (DI), konfigurace a řízení životního cyklu aplikace. Další informace najdete v tématu Obecný hostitel .NET v ASP.NET Core a Úlohy na pozadí s hostovanými službami v ASP.NET Core.

Servery

Aplikace ASP.NET Core používá k naslouchání požadavkům HTTP implementaci serveru HTTP. Server zjevuje požadavky aplikaci jako sadu funkcí požadavků sestavených do kontextu HttpContext.

Windows

ASP.NET Core nabízí následující implementace serveru:

• Kestrel je webový server pro různé platformy. Kestrel se často spouští v konfiguraci reverzního proxy serveru pomocí služby IIS. V systému ASP.NET Core 2.0 a novějších můžete Kestrel spustit jako veřejně přístupný hraniční server vystavený přímo na internetu.
• IIS HTTP Server je server pro Windows, který používá službu IIS. S tímto serverem se aplikace ASP.NET Core a služba IIS spouští ve stejném procesu.
• HTTP.sys je server pro Windows, který se nepoužívá se službou IIS.

macOS

ASP.NET Core poskytuje implementaci multiplatformního serveru Kestrel. V ASP.NET Core verzi 2.0 nebo novější lze Kestrel spustit jako veřejný hraniční server vystavený přímo na internetu. Kestrel se často spouští v konfiguraci reverzního proxy serveru pomocí Nginx nebo Apache.

Linux

ASP.NET Core poskytuje implementaci multiplatformního serveru Kestrel. V ASP.NET Core verzi 2.0 nebo novější lze Kestrel spustit jako veřejný hraniční server vystavený přímo na internetu. Kestrel se často spouští v konfiguraci reverzního proxy serveru pomocí Nginx nebo Apache.

Další informace najdete v tématu Implementace webových serverů v ASP.NET Core.

Konfigurace

ASP.NET Core poskytuje architekturu konfigurace, která získá nastavení jako páry název-hodnota od seřazené sady zprostředkovatelů konfigurace. Předdefinovaní zprostředkovatelé konfigurace jsou k dispozici pro různé zdroje, jako jsou soubory .json, soubory .xml, proměnné prostředí a argumenty příkazového řádku. Napište vlastní zprostředkovatele konfigurace pro podporu jiných zdrojů.

Ve výchozím nastavení jsou aplikace ASP.NET Core nakonfigurované pro čtení ze souboru appsettings.json, proměnných prostředí, příkazového řádku a dalších. Když se načte konfigurace aplikace, hodnoty z proměnných prostředí přepíší hodnoty ze souboru appsettings.json.

Pro správu důvěrných konfiguračních dat, jako jsou hesla ve vývojovém prostředí, poskytuje .NET CoreSecret Manager . Pro produkční tajné kódy doporučujeme Azure Key Vault.

Další informace najdete v tématu Konfigurace v ASP.NET Core.

Prostředí

V ASP.NET Core jsou k dispozici prostředí spouštění, například Development, Staging a Production. Zadejte prostředí, ve kterém aplikace běží, nastavením proměnné prostředí ASPNETCORE_ENVIRONMENT. ASP.NET Core přečte proměnnou prostředí při spuštění aplikace a uloží hodnotu v implementaci IWebHostEnvironment. Tato implementace je dostupná kdekoli v aplikaci prostřednictvím injektáže závislostí (DI).

Následující příklad nakonfiguruje obslužnou rutinu výjimek a middleware HTTP Strict Transport Security Protocol (HSTS) v případě, když se nespouští v prostředí Development:

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

Další informace viz Použití více prostředí v ASP.NET Core.

Protokolování

ASP.NET Core podporuje rozhraní API protokolování, které funguje s různými integrovanými poskytovateli protokolování a poskytovateli protokolování třetích stran. Mezi dostupné poskytovatele patří:

• Konzola
• Ladění
• Trasování událostí ve Windows
• Protokol událostí Windows
• TraceSource
• Azure App Service
• Azure Application Insights

Chcete-li vytvořit protokoly, přeložte službu ILogger<TCategoryName> z injektáže závislostí (DI) a volejte metody protokolování, jako je LogInformation. Následující příklad ukazuje, jak získat a použít logger v souboru .razor pro stránku v Blazor Web App. Objekt loggeru a zprostředkovatel konzoly jsou pro něj uloženy v kontejneru DI automaticky, když je metoda CreateBuilder volána v 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);
    }
}

Další informace najdete v článku o protokolování v .NET Core a ASP.NET Core.

Směrování

Směrování v ASP.NET Core je mechanismus, který mapuje příchozí požadavky na konkrétní koncové body v aplikaci. Umožňuje definovat vzory adres URL, které odpovídají různým komponentám, jako jsou komponenty Blazor, Razor stránky, akce kontroleru MVC nebo middleware.

Metoda UseRouting(IApplicationBuilder) přidá middleware směrování do potrubí požadavků. Tento middleware zpracovává informace o směrování a určuje odpovídající koncový bod pro každý požadavek. Pokud nechcete změnit pořadí zpracování middlewaru, nemusíte explicitně volat UseRouting.

Další informace naleznete v tématu Směrování v ASP.NET Core a ASP.NET Core Blazor směrování a navigace.

Zpracování chyb

ASP.NET Core obsahuje integrované funkce pro zpracování chyb, například:

• Stránka výjimky pro vývojáře
• Stránky vlastních chyb
• Statické stránky stavového kódu
• Ošetření výjimek při spuštění

Další informace najdete v tématu Zpracování chyb v ASP.NET Core.

Vytváření požadavků HTTP

Implementace IHttpClientFactory je k dispozici pro vytváření instancí HttpClient. Objekt pro vytváření:

• Poskytuje centrální umístění pro pojmenování a konfiguraci logických instancí HttpClient. Zaregistrujte a nakonfigurujte například klienta github pro přístup ke GitHubu. Zaregistrujte a nakonfigurujte výchozího klienta pro jiné účely.
• Podporuje registraci a řetězení více obslužných rutin delegování pro sestavení kanálu middlewaru odchozích požadavků. Tento model se podobá příchozímu kanálu middlewaru ASP.NET Core. Model poskytuje mechanismus pro správu obecně se vyskytujících problémů s požadavky HTTP, včetně ukládání do mezipaměti, zpracování chyb, serializace a protokolování.
• Integruje se s Polly, oblíbenou knihovnou třetí strany pro zpracování přechodných chyb.
• Spravuje sdružování a dobu života základních instancí HttpClientHandler, aby se zabránilo běžným problémům s DNS, ke kterým dochází při ruční správě doby života HttpClient.
• Přidává konfigurovatelné prostředí protokolování prostřednictvím rozhraní ILogger pro všechny požadavky odeslané klienty vytvořenými objektem pro vytváření.

Další informace najdete v tématu Vytváření požadavků HTTP pomocí IHttpClientFactory v ASP.NET Core.

Kořen obsahu

Kořen obsahu je základní cesta pro:

• Spustitelný soubor hostující aplikaci (.exe)
• Kompilovaná sestavení, která tvoří aplikaci (.dll)
• Soubory obsahu používané aplikací, například:
  • Soubory Razor (.cshtml, .razor)
  • Konfigurační soubory (.json, .xml)
  • Datové soubory (.db)
• Kořen webu, obvykle složka wwwroot

Během vývoje se jako výchozí kořen obsahu použije kořenový adresář projektu. Tento adresář je také základní cestou pro soubory obsahu aplikace i kořen webu. Zadejte jiný kořen obsahu nastavením jeho cesty při sestavování hostitele. Další informace najdete v tématu Kořen obsahu.

Kořen webu

Kořen webu je základní cesta pro veřejné statické soubory prostředků, například:

• Šablony stylů (.css)
• JavaScript (.js)
• Obrázky (.png, .jpg)

Ve výchozím nastavení se statické soubory obsluhují pouze z kořenového adresáře webu a jeho podadresářů. Výchozí hodnota kořenové cesty webu je {content root}/wwwroot. Zadejte jiný kořen webu nastavením jeho cesty při sestavování hostitele. Další informace najdete v tématu Kořen webu.

Zabraňte publikování souborů v adresáři wwwroot pomocí položky projektu <Content> v souboru projektu. Následující příklad brání publikování obsahu v adresáři wwwroot/local a jeho podadresářích:

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

V souborech Razor.cshtml odkazuje ~/ na kořen webu. Cesta začínající na ~/ se označuje jako virtuální cesta.

Další informace najdete v tématu Statické soubory v ASP.NET Core.

Další materiály

• základy ASP.NET Core