Overzicht van basisinformatie over ASP.NET Core

Dit artikel bevat een overzicht van de basisprincipes voor het bouwen van ASP.NET Core-apps, waaronder afhankelijkheidsinjectie (DI), configuratie, middleware en meer.

Zie voor fundamentele richtlijnen over Blazor, die de richtlijnen in dit artikel aanvullen of vervangen, ASP.NET Core basisprincipes Blazor.

Program.cs

ASP.NET Core-apps die zijn gemaakt met de websjablonen, bevatten de opstartcode van de toepassing in het Program.cs-bestand. Het Program.cs-bestand is waar:

• Services die door de app zijn vereist, worden geconfigureerd.
• De aanvraagafhandelingspijplijn van de app wordt gedefinieerd als een reeks middlewareonderdelen.

De volgende opstartcode voor apps ondersteunt verschillende app-typen:

• Blazor Web Apps
• Razor pagina's
• MVC-controllers met weergaven
• Web-API met controllers
• Minimale web-API's

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

Afhankelijkheidsinjectie (diensten)

ASP.NET Core beschikt over ingebouwde afhankelijkheidsinjectie (DI) die geconfigureerde services beschikbaar maakt in een app. Services worden in het bovenstaande voorbeeld aan de DI-container toegevoegd met WebApplicationBuilder.Services, builder.Services. Wanneer de WebApplicationBuilder wordt geïnstantieerd, worden veel door het framework geleverde services automatisch toegevoegd. builder is een WebApplicationBuilder in de volgende code:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

In de voorgaande code voegt CreateBuilder configuratie, logboekregistratie en vele andere services toe aan de DI-container. Het DI-framework biedt een exemplaar van een aangevraagde service tijdens runtime.

De volgende code voegt een aangepaste DbContext en Blazor onderdelen toe aan de DI-container:

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

In Blazor Web Appworden services vaak opgelost vanuit DI tijdens runtime met behulp van de @inject-instructie in een Razor onderdeel, zoals wordt weergegeven in het volgende voorbeeld:

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

In de voorgaande code:

• De @inject richtlijn wordt gebruikt.
• De service wordt opgelost in de OnInitialized methode en toegewezen aan de variabele context.
• De context service maakt de FilteredMovie lijst.

Een andere manier om een service van DI op te lossen, is door constructorinjectie te gebruiken. De volgende Razor Pages-code maakt gebruik van constructorinjectie om de databasecontext en een logger van DI op te lossen:

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

In de voorgaande code neemt de IndexModel constructor een parameter van het type RazorPagesMovieContext, die tijdens runtime wordt omgezet in de _context variabele. Het contextobject wordt gebruikt om een lijst met films te maken in de methode OnGetAsync.

Zie ASP.NET Core Blazor-afhankelijkheidsinjectie en Afhankelijkheidsinjectie in ASP.NET Corevoor meer informatie.

Middleware

De pijplijn voor het verwerken van aanvragen is samengesteld als een reeks middlewareonderdelen. Elk onderdeel voert bewerkingen uit op een HttpContext en roept de volgende middleware in de pijplijn aan of beëindigt de aanvraag.

Volgens de conventie wordt een middleware-onderdeel aan de pijplijn toegevoegd door een Use{Feature}-extensiemethode aan te roepen. Het gebruik van methoden met de naam Use{Feature} om middleware toe te voegen aan een app, wordt geïllustreerd in de volgende code:

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

Zie ASP.NET Core Middlewarevoor meer informatie.

Gastheer

Bij het opstarten bouwt een ASP.NET Core-app een host. De host bevat alle resources van de app, zoals:

• Een HTTP-server-implementatie
• Middlewareonderdelen
• Loggen
• Afhankelijkheidsinjectie-diensten (DI)
• Configuratie

Er zijn drie verschillende hosts die een ASP.NET Core-app kunnen uitvoeren:

• ASP.NET Core WebApplication, ook wel bekend als de Minimale Host
• .NET Generic Host gecombineerd met de ConfigureWebHostDefaults van ASP.NET Core
• ASP.NET Core WebHost

De typen ASP.NET Core WebApplication en WebApplicationBuilder worden aanbevolen en worden gebruikt in alle ASP.NET Core-sjablonen. WebApplication gedraagt zich op dezelfde manier als de .NET Generic Host en maakt veel van dezelfde interfaces beschikbaar, maar vereist minder callbacks om te configureren. De ASP.NET Core-WebHost is alleen beschikbaar voor achterwaartse compatibiliteit.

In het volgende voorbeeld wordt een WebApplication geïnstitueert en toegewezen aan een variabele met de naam 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();

De methode WebApplicationBuilder.Build configureert een host met een set standaardopties, zoals:

• Gebruik Kestrel als webserver en schakel IIS-integratie in.
• Laad configuratie uit appsettings.json, omgevingsvariabelen, opdrachtregelargumenten en andere configuratiebronnen.
• Logboekuitvoer verzenden naar de console en foutopsporingsproviders.

Niet-webscenario's

Met de Generic Host kunnen andere typen apps gebruikmaken van geavanceerde frameworkextensies, zoals logboekregistratie, afhankelijkheidsinjectie (DI), configuratie en levensduurbeheer van apps. Voor meer informatie, zie .NET Generic Host in ASP.NET Core en Achtergrondtaken met gehoste services in ASP.NET Core.

Servers

Een ASP.NET Core-app maakt gebruik van een HTTP-server-implementatie om te luisteren naar HTTP-aanvragen. De server behandelt aanvragen voor de app als een set aanvraagfuncties samengesteld in een HttpContext.

Windows

ASP.NET Core biedt de volgende server-implementaties:

• Kestrel is een platformoverschrijdende webserver. Kestrel wordt vaak uitgevoerd in een omgekeerde proxyconfiguratie met behulp van IIS-. In ASP.NET Core 2.0 en hoger kan Kestrel worden uitgevoerd als een openbare edge-server die rechtstreeks beschikbaar is voor internet.
• IIS HTTP-server is een server voor Windows die IIS gebruikt. Met deze server worden de ASP.NET Core-app en IIS in hetzelfde proces uitgevoerd.
• HTTP.sys is een server voor Windows die niet wordt gebruikt met IIS.

macOS

ASP.NET Core biedt de Kestrel-implementatie van een platformoverschrijdende server. In ASP.NET Core 2.0 of hoger kan Kestrel worden uitgevoerd als een openbare edge-server die rechtstreeks beschikbaar is op internet. Kestrel wordt vaak uitgevoerd in een omgekeerde proxyconfiguratie met Nginx- of Apache.

Linux

ASP.NET Core biedt de platformoverschrijdende serverimplementatie van Kestrel. In ASP.NET Core 2.0 of hoger kan Kestrel worden uitgevoerd als een openbare edge-server die rechtstreeks beschikbaar is op internet. Kestrel wordt vaak uitgevoerd in een omgekeerde proxyconfiguratie met Nginx- of Apache.

Zie webserver-implementaties in ASP.NET Corevoor meer informatie.

Configuratie

ASP.NET Core biedt een configuratie framework waarmee instellingen worden opgehaald als naam-waardeparen van een geordende set configuratieproviders. Ingebouwde configuratieproviders zijn beschikbaar voor verschillende bronnen, zoals .json bestanden, .xml bestanden, omgevingsvariabelen en opdrachtregelargumenten. Schrijf aangepaste configuratieproviders om andere bronnen te ondersteunen.

Door standaard, zijn ASP.NET Core-apps geconfigureerd om te lezen uit appsettings.json, omgevingsvariabelen, de opdrachtregel en meer. Wanneer de configuratie van de app wordt geladen, overschrijven waarden uit omgevingsvariabelen waarden uit appsettings.json.

Voor het beheren van vertrouwelijke configuratiegegevens, zoals wachtwoorden in de ontwikkelomgeving, biedt .NET Core de Secret Manager-. Voor productiegeheimen raden we Azure Key Vault-aan.

Zie Configuratie in ASP.NET Corevoor meer informatie.

Omgevingen

Uitvoeringsomgevingen, zoals Development, Stagingen Production, zijn beschikbaar in ASP.NET Core. Geef de omgeving op waarin een app wordt uitgevoerd door de ASPNETCORE_ENVIRONMENT omgevingsvariabele in te stellen. ASP.NET Core leest die omgevingsvariabele bij het opstarten van de app en slaat de waarde op in een IWebHostEnvironment-implementatie. Deze implementatie is overal in een app beschikbaar via afhankelijkheidsinjectie (DI).

In het volgende voorbeeld worden de uitzonderingshandler en HSTS (HTTP Strict Transport Security Protocol) middleware geconfigureerd wanneer niet uitgevoerd in de Development-omgeving:

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

Zie Meerdere omgevingen gebruiken in ASP.NET Corevoor meer informatie.

Loggen

ASP.NET Core ondersteunt een logboekregistratie-API die werkt met diverse ingebouwde en externe logboekregistratieproviders. Beschikbare providers zijn onder andere:

• Console
• Fouten opsporen
• Gebeurtenistracering in Windows
• Windows-gebeurtenislogboek
• TraceSource
• Azure App Service
• Azure Application Insights

Als u logboeken wilt maken, moet u een ILogger<TCategoryName>-service oplossen op basis van afhankelijkheidsinjectie (DI) en methoden voor logboekregistratie aanroepen, zoals LogInformation. Het volgende voorbeeld laat zien hoe je een logger kunt verkrijgen en gebruiken in een .razor-bestand voor een pagina in een Blazor Web App. Een loggerobject en een consoleprovider worden automatisch opgeslagen in de DI-container wanneer de methode CreateBuilder wordt aangeroepen in 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);
    }
}

Zie Logboekregistratie in .NET Core en ASP.NET Corevoor meer informatie.

Routering

Routering in ASP.NET Core is een mechanisme waarmee binnenkomende aanvragen worden toegewezen aan specifieke eindpunten in een toepassing. Hiermee kunt u URL-patronen definiëren die overeenkomen met verschillende onderdelen, zoals Blazor onderdelen, Razor pagina's, MVC-controlleracties of middleware.

De methode UseRouting(IApplicationBuilder) voegt routerings-middleware toe aan de aanvraagpijplijn. Deze middleware verwerkt de routeringsinformatie en bepaalt het juiste eindpunt voor elke aanvraag. U hoeft niet expliciet UseRouting aan te roepen, tenzij u de volgorde wilt wijzigen waarin middleware wordt verwerkt.

Zie Routering in ASP.NET Core en ASP.NET Core Blazor routering en navigatievoor meer informatie.

Foutafhandeling

ASP.NET Core heeft ingebouwde functies voor het afhandelen van fouten, zoals:

• Een uitzonderingspagina voor ontwikkelaars
• Aangepaste foutpagina's
• Pagina's met statische statuscode
• Afhandeling van opstartonderzondering

Zie Fouten afhandelen in ASP.NET Corevoor meer informatie.

HTTP-aanvragen maken

Er is een implementatie van IHttpClientFactory beschikbaar voor het maken van HttpClient instanties. De fabriek:

• Biedt een centrale locatie voor het benoemen en configureren van logische HttpClient instanties. Registreer en configureer bijvoorbeeld een github--client voor toegang tot GitHub. Registreer en configureer een standaardclient voor andere doeleinden.
• Ondersteunt registratie en ketening van meerdere delegerende handlers voor het bouwen van een middleware-pijplijn voor uitgaande aanvragen. Dit patroon is vergelijkbaar met de binnenkomende middleware-pijplijn van ASP.NET Core. Het patroon biedt een mechanisme voor het beheren van overschrijdende problemen voor HTTP-aanvragen, waaronder caching, foutafhandeling, serialisatie en logboekregistratie.
• Integreert met Polly, een populaire bibliotheek van een derde partij voor tijdelijke foutafhandeling.
• Beheert de pooling en levensduur van onderliggende HttpClientHandler instanties om veelvoorkomende DNS-problemen te voorkomen die zich voordoen wanneer de levensduur van HttpClient handmatig wordt beheerd.
• Voegt een configureerbare logboekregistratie-ervaring toe via ILogger voor alle aanvragen die worden verzonden via clients die door de fabriek zijn gemaakt.

Zie HTTP-aanvragen maken met IHttpClientFactory in ASP.NET Corevoor meer informatie.

Inhoudsroot

De inhoudsroot is het basispad voor:

• Het uitvoerbare bestand dat als host fungeert voor de app (.exe).
• Gecompileerde assembly's waaruit de app bestaat (.dll).
• Inhoudsbestanden die door de app worden gebruikt, zoals:
  • Razor bestanden (.cshtml, .razor)
  • Configuratiebestanden (.json, .xml)
  • Gegevensbestanden (.db)
• De webhoofdmap, meestal de map wwwroot.

Tijdens de ontwikkeling wordt de hoofdmap van de inhoud standaard ingesteld op de hoofdmap van het project. Deze map is ook het basispad voor zowel de inhoudsbestanden van de app als de webhoofdmap. Geef een andere inhoudshoofdmap op door het pad in te stellen wanneer de hostte bouwen. Voor meer informatie, zie Content root.

webroot

De root is het basispad voor openbare, statische bronbestanden, zoals:

• Opmaakmodellen (.css)
• JavaScript (.js)
• Afbeeldingen (.png, .jpg)

Statische bestanden worden standaard alleen geleverd vanuit de hoofdmap van het web en de bijbehorende submappen. Het webhoofdpad wordt standaard ingesteld op {content root}/wwwroot. Geef een andere webhoofdmap op door het pad in te stellen wanneer de host bouwt. Zie webrootvoor meer informatie.

Voorkomen dat bestanden in wwwroot- worden gepubliceerd met het <Projectitem> projectitem in het projectbestand. In het volgende voorbeeld wordt voorkomen dat inhoud wordt gepubliceerd in wwwroot/local en de bijbehorende submappen:

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

In bestanden Razor.cshtml verwijst ~/ naar de hoofdmap van het web. Een pad dat begint met ~/ wordt een virtueel padgenoemd.

Zie Statische bestanden in ASP.NET Corevoor meer informatie.

Aanvullende informatiebronnen

• basisprincipes van ASP.NET Core Blazor