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í.
• Kanál zpracování požadavků aplikace se definuje jako řada komponent middlewaru.

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

• Blazor Web Apps
• Razor Stránky
• 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í WebApplicationBuilder.Servicesbuilder.Services v předchozím kódu. 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.

Host

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
• Logging
• Služby injektáže závislostí (DI)
• Configuration

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 konfiguruje hostitele se sadou výchozích možností, například:

• Použít Kestrel jako webový server a povolit integraci služby IIS
• Načtení konfigurace z 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í

Jiné než webové 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.

Servers

Aplikace ASP.NET Core používá k naslouchání požadavkům HTTP implementaci serveru HTTP. Server vystavuje požadavky do aplikace jako sadu funkcí požadavků, které se skládají do .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 ASP.NET Core verzi 2.0 nebo novější lze Kestrel spustit jako veřejný 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.

Configuration

ASP.NET Core poskytuje konfigurační architekturu, která získá nastavení jako páry název-hodnota z 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í z 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 Správce tajných kódů. Pro produkční tajné kódy doporučujeme Azure Key Vault.

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

Environments

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 najdete v tématu prostředí runtime ASP.NET Core.

Logging

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ří:

• Console
• Debug
• 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 Fahrenheit">Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    private WeatherForecast[]? forecasts;

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

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

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

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

Další informace najdete v tématu Protokolování v .NET a ASP.NET Core.

Routing

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 GitHubu pro přístup k 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ích stran 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řenový adresář 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řenový adresář webu, obvykle složkawwwroot.

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 webový kořenový adresář. Zadejte jiný kořen obsahu nastavením jeho cesty při sestavování hostitele. Další informace najdete v tématu Kořen obsahu.

Kořenový adresář 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 webové kořenové cesty je {CONTENT ROOT}/wwwroot, kde značka {CONTENT ROOT} je kořen obsahu. Zadejte jiný kořen webu nastavením jeho cesty při sestavování hostitele. Další informace naleznete v tématu Kořenový adresář webu.

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

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

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

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

Jak si stáhnout ukázku

Řada článků a kurzů obsahuje odkazy na vzorový kód.

1. Stáhněte si soubor zip úložiště ASP.NET.
2. Rozbalte AspNetCore.Docs-main.zip soubor.
3. Pokud chcete získat přístup k ukázkové aplikaci článku v rozbaleném úložišti, použijte adresu URL v ukázkovém odkazu článku, který vám pomůže přejít do složky ukázky. Obvykle se v horní části článku zobrazí ukázkový odkaz s textem odkazu Zobrazení nebo stažením ukázkového kódu.

Direktivy preprocesoru ve vzorovém kódu

K předvedení více scénářů používají #define ukázkové aplikace direktivy preprocesoru k selektivní kompilaci a #if-#else/#elif-#endif spouštění různých částí vzorového kódu. U ukázek, které tento přístup využívají, nastavte #define direktivu v horní části souborů C# tak, aby definovala symbol přidružený ke scénáři, který chcete spustit. Některé ukázky vyžadují definování symbolu v horní části více souborů, aby bylo možné spustit scénář.

Například následující seznam symbolů #define udává, že jsou dostupné čtyři scénáře (jeden scénář na symbol). Při aktuální konfiguraci ukázky se spustí scénář TemplateCode:

#define TemplateCode // or LogFromMain or ExpandDefault or FilterInCode

Pokud chcete ukázku změnit tak, aby se spustil scénář ExpandDefault, definujte symbol ExpandDefault a zbývající symboly nechejte zakomentované:

#define ExpandDefault // TemplateCode or LogFromMain or FilterInCode

Další informace o používání direktiv preprocesoru C# k selektivní kompilaci částí kódu najdete v článku #define (referenční dokumentace jazyka C# ) a #if (referenční dokumentace jazyka C#).

Oblasti v ukázkovém kódu

Některé ukázkové aplikace obsahují části kódu obklopené direktivami #region a #endregion jazyka C#. Systém sestavení dokumentace vloží tyto oblasti do témat vykreslené dokumentace.

Názvy oblastí obvykle obsahují slovo "fragment". Následující příklad ukazuje oblast s názvem snippet_WebHostDefaults:

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

Předchozí fragment kódu jazyka C# se odkazuje v souboru markdownu tématu s následujícím řádkem:

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

Můžete bezpečně ignorovat nebo odebrat direktivy #region , #endregion které kód obklopují. Kód v těchto direktivách neměňte, pokud plánujete spustit ukázkové scénáře popsané v tématu.

Další informace najdete v dokumentaci k ASP.NET: Fragmenty kódu.

Dodatečné zdroje

základy ASP.NET Core