Panoramica dei concetti fondamentali di ASP.NET Core

Questo articolo offre una panoramica dei concetti fondamentali per la creazione di app ASP.NET Core, tra cui inserimento delle dipendenze, configurazione, middleware e altro ancora.

Per la guida sui fondamentali di Blazor, che aggiunge o sostituisce le linee guida in questo articolo, vedere ASP.NET Core nozioni fondamentali Blazor.

Program.cs

Le app ASP.NET Core create con i modelli Web contengono il codice di avvio dell'applicazione nel file Program.cs. Nel file Program.cs:

• Vengono configurati i servizi necessari per l'app.
• La pipeline di gestione delle richieste dell'app è definita come una serie di componenti middleware.

Il codice di avvio dell'app seguente supporta diversi tipi di app:

• Blazor Web Apps
• Razor Pagine
• Controller MVC con visualizzazioni
• API Web con controller
• API Web minime

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

Inserimento di dipendenze (servizi)

ASP.NET Funzionalità di base predefinite di inserimento delle dipendenze che rende disponibili i servizi configurati in un'app. I servizi vengono aggiunti al contenitore DI con WebApplicationBuilder.Services, builder.Services nel codice precedente. Quando viene creata un'istanza di WebApplicationBuilder, molti servizi forniti dal framework vengono aggiunti automaticamente. builder è un WebApplicationBuilder nel codice seguente:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Nel codice precedente, CreateBuilder aggiunge configurazione, gestione dei log e altri numerosi servizi al contenitore delle dipendenze. Il framework DI fornisce un'istanza di un servizio richiesto a runtime.

Il codice seguente aggiunge i componenti personalizzati DbContext e Blazor al contenitore DI:

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 Appi servizi vengono spesso risolti dalla DI a tempo di esecuzione usando la direttiva @inject in un componente Razor, come illustrato nell'esempio seguente.

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

Nel codice precedente:

• Viene utilizzata la direttiva @inject.
• Il servizio viene risolto nel metodo OnInitialized e assegnato alla variabile context.
• Il servizio context crea l'elenco FilteredMovie.

Un altro modo per risolvere un servizio dal contenitore DI consiste nell'usare l'iniezione del costruttore. Il codice seguente di Razor Pages utilizza l'inserimento del costruttore per risolvere il contesto del database e un logger tramite Dependency Injection (inserimento delle dipendenze):

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

Nel codice precedente, il costruttore IndexModel accetta un parametro di tipo RazorPagesMovieContext, che viene risolto in fase di esecuzione nella variabile _context. L'oggetto contesto viene usato per creare un elenco di film nel metodo OnGetAsync.

Per ulteriori informazioni, vedere iniezione di dipendenze di ASP.NET Core Blazor e Iniezione di dipendenze in ASP.NET Core.

Middleware

La pipeline di gestione delle richieste è strutturata come una serie di componenti middleware. Ogni componente esegue operazioni asincrone in un HttpContext, quindi richiama il middleware successivo nella pipeline oppure termina la richiesta.

Per convenzione viene aggiunto un componente middleware alla pipeline richiamando un metodo di estensione Use{Feature}. L'uso di metodi denominati Use{Feature} per aggiungere middleware a un'app è illustrato nel codice seguente:

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

Per altre informazioni, vedere Middleware ASP.NET Core.

Host

All'avvio, un'app ASP.NET Core crea un host. L'host incapsula tutte le risorse dell'app, ad esempio:

• Un'implementazione del server HTTP
• Componenti middleware
• Logging
• Servizi di inserimento delle dipendenze
• Configuration

Esistono tre host diversi in grado di eseguire un'app ASP.NET Core:

• ASP.NET Core WebApplication, noto anche come host minimo
• Host generico .NET combinato con ASP.NET Core ConfigureWebHostDefaults
• ASP.NET Core WebHost

I tipi ASP.NET Core WebApplication e WebApplicationBuilder sono consigliati e vengono usati in tutti i modelli ASP.NET Core. WebApplication si comporta in modo analogo all'host generico .NET ed espone molte delle stesse interfacce, ma richiede meno callback per la configurazione. Il ASP.NET Core WebHost è disponibile solo per la compatibilità con le versioni precedenti.

L'esempio seguente istanzia un WebApplication e lo assegna a una variabile chiamata 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();

Il metodo WebApplicationBuilder.Build configura un host con un set di opzioni predefinite, ad esempio:

• Usare Kestrel come server Web e abilitare l'integrazione IIS.
• Caricare la configurazione da appsettings.json, variabili di ambiente, argomenti della riga di comando e altre origini di configurazione.
• Inviare l'output di registrazione alla console e ai provider di debug.

Scenari non Web

L'host generico consente ad altri tipi di applicazioni di usare estensioni del framework trasversali, ad esempio il log, l'inserimento delle dipendenze (DI), la configurazione e la gestione del ciclo di vita delle applicazioni. Per altre informazioni, vedere Host generico .NET in ASP.NET Core e Attività in background con servizi ospitati in ASP.NET Core.

Servers

Un'app ASP.NET Core usa un'implementazione del server HTTP per l'ascolto delle richieste HTTP. Il server espone le richieste all'app come set di funzionalità di richiesta composte in un oggetto HttpContext.

Windows

ASP.NET Core include le implementazioni server seguenti:

• Kestrel è un server Web multipiattaforma. Kestrel viene spesso eseguito in una configurazione di proxy inverso tramite IIS. In ASP.NET Core 2.0 o versione successiva Kestrel può essere eseguito come server perimetrale pubblico esposto direttamente a Internet.
• Server HTTP IIS è un server per Windows che usa IIS. Con questo server l'app ASP.NET Core e IIS sono eseguiti nello stesso processo.
• HTTP.sys è un server per Windows che non viene usato con IIS.

macOS

ASP.NET Core fornisce l'implementazione del server multipiattaforma Kestrel. In ASP.NET Core 2.0 o versione successiva Kestrel può essere eseguito come server perimetrale pubblico esposto direttamente a Internet. Kestrel viene spesso eseguito in una configurazione del proxy inverso con Nginx o Apache.

Linux

ASP.NET Core fornisce l'implementazione del server multipiattaforma Kestrel. In ASP.NET Core 2.0 o versione successiva Kestrel può essere eseguito come server perimetrale pubblico esposto direttamente a Internet. Kestrel viene spesso eseguito in una configurazione del proxy inverso con Nginx o Apache.

Per altre informazioni, vedere Implementazioni del server Web in ASP.NET Core.

Configuration

ASP.NET Core fornisce un framework di configurazione che ottiene le impostazioni come coppie nome-valore da un set ordinato di provider di configurazione. Sono disponibili provider di configurazione predefiniti per un'ampia gamma di origini, ad esempio file .json, file .xml, variabili di ambiente e argomenti della riga di comando. Scrivere provider di configurazione personalizzati per supportare altre origini.

Per impostazione predefinita, le app ASP.NET Core sono configurate per leggere da appsettings.json, variabili di ambiente, riga di comando e altro ancora. Quando viene caricata la configurazione dell'app, i valori delle variabili di ambiente sostituiscono i valori di appsettings.json.

Per la gestione dei dati di configurazione riservati, ad esempio le password nell'ambiente di sviluppo, .NET fornisce Secret Manager. Per i segreti di produzione, si consiglia di usare Azure Key Vault.

Per altre informazioni, vedere Configurazione in ASP.NET Core.

Environments

In ASP.NET Core sono disponibili ambienti di esecuzione, ad esempio Development, Staging e Production. Specificare l'ambiente in cui viene eseguita un'app impostando la variabile di ambiente ASPNETCORE_ENVIRONMENT. ASP.NET Core legge tale variabile di ambiente all'avvio dell'app e ne archivia il valore in un'implementazione IWebHostEnvironment. Questa implementazione è disponibile ovunque in un'app tramite inserimento delle dipendenze.

Nell'esempio seguente vengono configurati il gestore eccezioni e il middleware HSTS (HTTP Strict Transport Security Protocol) quando non in esecuzione nell'ambiente Development:

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

Per altre informazioni, vedere Ambienti di runtime di ASP.NET Core.

Logging

ASP.NET Core supporta un'API di registrazione che funziona con un'ampia gamma di provider di registrazione predefiniti e di terze parti. I provider disponibili includono:

• Console
• Debug
• Event Tracing for Windows
• Registro eventi di Windows
• TraceSource
• Servizio app di Azure
• Azure Application Insights

Per creare i log, risolvere un servizio ILogger<TCategoryName> dall'inserimento delle dipendenze e chiamare metodi di registrazione, come LogInformation. Nell'esempio seguente viene illustrato come ottenere e utilizzare un logger in un file .razor per una pagina in Blazor Web App. Un oggetto logger e un provider di console per esso vengono archiviati automaticamente nel contenitore DI quando il metodo CreateBuilder viene chiamato 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);
    }
}

Per altre informazioni, vedere Registrazione in .NET e ASP.NET Core.

Routing

Il routing in ASP.NET Core è un meccanismo che associa le richieste in ingresso a endpoint specifici in un'applicazione. Consente di definire modelli url che corrispondono a componenti diversi, ad esempio componenti Blazor, pagine Razor, azioni del controller MVC o middleware.

Il metodo UseRouting(IApplicationBuilder) aggiunge il middleware di routing alla pipeline di richiesta. Questo middleware elabora le informazioni di routing e determina l'endpoint appropriato per ogni richiesta. Non è necessario chiamare in modo esplicito UseRouting a meno che non si voglia modificare l'ordine in cui viene elaborato il middleware.

Per altre informazioni, vedere Routing in ASP.NET Core e ASP.NET Core Blazor routing e navigazione.

Gestione degli errori

ASP.NET Core dispone di funzionalità predefinite per la gestione degli errori, ad esempio:

• Una pagina delle eccezioni per gli sviluppatori
• Pagine di errore personalizzate
• Pagine dei codici di stato statiche
• Gestione delle eccezioni durante l'avvio

Per altre informazioni, vedere Gestire gli errori in ASP.NET Core.

Effettuare richieste HTTP

Un'implementazione di IHttpClientFactory è disponibile per la creazione di istanze HttpClient. Il factory:

• Offre una posizione centrale per la denominazione e la configurazione di istanze di HttpClient logiche. Ad esempio, registrare e configurare un client GitHub per l'accesso a GitHub. Registrare e configurare un client predefinito per altri scopi.
• Supporta la registrazione e il concatenamento di più gestori di delega per creare una pipeline di middleware per le richieste in uscita. Questo modello è simile alla pipeline di middleware in ingresso di ASP.NET Core. Il modello offre un meccanismo per gestire le problematiche trasversali relative alle richieste HTTP, tra cui memorizzazione nella cache, gestione degli errori, serializzazione e registrazione.
• Si integra con Polly, una popolare libreria di terze parti per la gestione degli errori temporanei.
• Gestisce il pooling e la durata delle istanze di HttpClientHandler sottostanti per evitare problemi DNS comuni che si verificano quando le durate di HttpClient vengono gestite manualmente.
• Aggiunge un'esperienza di registrazione configurabile tramite ILogger per tutte le richieste inviate attraverso i client creati dalla factory.

Per altre informazioni, vedere Effettuare richieste HTTP usando IHttpClientFactory in ASP.NET Core.

Radice del contenuto

La radice del contenuto è il percorso di base per:

• Eseguibile che ospita l'app (.exe).
• Gli assembly compilati che costituiscono l'app (.dll).
• File di contenuto usati dall'app, ad esempio:
  • File Razor (.cshtml, .razor)
  • File di configurazione (.json, .xml)
  • File di dati (.db)
• Radice Web, in genere la cartella wwwroot.

Durante lo sviluppo, per impostazione predefinita la radice del contenuto è la directory radice del progetto. Questa directory è anche il percorso di base per i file di contenuto dell'app e la radice Web. Specificare una radice del contenuto diversa impostandone il percorso durante la compilazione dell'host. Per altre informazioni, vedere Radice del contenuto.

Radice del sito

La radice Web è il percorso di base per i file di risorse statici pubblici, ad esempio:

• Fogli di stile (.css)
• JavaScript (.js)
• Immagini (.png, .jpg)

Per impostazione predefinita, i file statici vengono forniti solo dalla directory radice Web e dalle relative sottodirectory. Per impostazione predefinita, il percorso radice Web è {CONTENT ROOT}/wwwroot, dove il segnaposto {CONTENT ROOT} è la radice del contenuto. Specificare una radice Web diversa impostandone il percorso durante la compilazione dell'host. Per altre informazioni, vedere Radice Web.

Impedire la pubblicazione di file in wwwroot con l'elemento del progetto <Content> nel file del progetto. Nell'esempio seguente viene impedita la pubblicazione di contenuto in wwwroot/local e le relative sottodirectory:

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

Nei file Razor.cshtml, ~/ punta alla radice Web. Un percorso che inizia con ~/ viene definito percorso virtuale.

Per altre informazioni, vedere File statici in ASP.NET Core.

Come scaricare un esempio

Molti articoli ed esercitazioni includono collegamenti al codice di esempio.

1. Scaricare il file ZIP del repository ASP.NET.
2. Decomprimere il file AspNetCore.Docs-main.zip.
3. Per accedere a un'app di esempio di un articolo nel repository decompresso, utilizzare l'URL fornito nel link di esempio dell'articolo per navigare alla cartella dell'esempio. In genere, il collegamento di esempio di un articolo viene visualizzato nella parte superiore dell'articolo con il testo del collegamento Visualizza o scarica il codice di esempio.

Direttive per il preprocessore nel codice di esempio

Per illustrare più scenari, le app di esempio usano le #define direttive del preprocessore e #if-#else/#elif-#endif per compilare ed eseguire in modo selettivo sezioni diverse del codice di esempio. Per gli esempi che usano questo approccio, impostare la #define direttiva all'inizio dei file C# per definire il simbolo associato allo scenario da eseguire. Alcuni esempi richiedono la definizione del simbolo nella parte superiore di più file per eseguire uno scenario.

Ad esempio, l'elenco di simboli #define seguente indica che sono disponibili quattro scenari, ovvero uno scenario per simbolo. La configurazione di esempio corrente esegue lo scenario TemplateCode:

#define TemplateCode // or LogFromMain or ExpandDefault or FilterInCode

Per modificare l'esempio in modo che venga eseguito lo scenario ExpandDefault, definire il simbolo ExpandDefault e lasciare i simboli rimanenti con commento:

#define ExpandDefault // TemplateCode or LogFromMain or FilterInCode

Per altre informazioni sull'uso delle direttive del preprocessore C# per compilare in modo selettivo le sezioni di codice, vedere #define (Riferimenti per C#) e #if (Riferimenti per C#).

Aree nel codice di esempio

Alcune app di esempio contengono sezioni di codice racchiuse tra #region e #endregion direttive C#. Il sistema di compilazione della documentazione inserisce queste aree negli argomenti della documentazione di cui è stato eseguito il rendering.

I nomi delle aree in genere contengono la parola "frammento". L'esempio seguente mostra un'area denominata snippet_WebHostDefaults:

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

Il frammento di codice C# precedente viene fatto riferimento nel file markdown dell'argomento con la riga seguente:

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

È possibile ignorare o rimuovere le direttive #region e #endregion che circondano il codice. Non modificare il codice all'interno di queste direttive se si prevede di eseguire gli scenari di esempio descritti nell'argomento.

Per altre informazioni, vedere Contribuire alla documentazione di ASP.NET: Frammenti di codice.

Risorse aggiuntive

ASP.NET Core Blazor concetti fondamentali