Condividi tramite

Panoramica dei concetti fondamentali di ASP.NET Core

  • Articolo

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 9 di questo articolo.

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere i criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 9 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 9 di questo articolo.

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.
  • Viene definita la pipeline di gestione delle richieste dell'app come una serie di componenti middleware.

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

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 inserimento delle dipendenze con WebApplicationBuilder.Services, builder.Services nel codice precedente. Quando viene creata un'istanza del WebApplicationBuilder, vengono aggiunti automaticamente molti servizi forniti dal framework. 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

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

  • Un'implementazione del server HTTP
  • I componenti middleware
  • Registrazione
  • Servizi di inserimento delle dipendenze
  • Impostazione

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

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

Server

Un'app ASP.NET Core usa un'implementazione del server HTTP per l'ascolto delle richieste HTTP. Il server espone le richieste all'app sotto forma di insieme di funzionalità di richiesta strutturate in un HttpContext.

ASP.NET Core include le implementazioni server seguenti:

  • Kestrel è un server Web multipiattaforma. Kestrel viene spesso eseguito in una configurazione con proxy inverso tramite IIS. In ASP.NET Core 2.0 e versioni successive, 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.

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

Impostazione

ASP.NET Core offre un framework di configurazione che ottiene le impostazioni, ad esempio 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 la lettura 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 Core fornisce Secret Manager. Per i segreti di produzione, si consiglia di usare Azure Key Vault.

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

Ambienti

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 Usare più ambienti in ASP.NET Core.

Registrazione

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
  • Azure App Service
  • 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 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);
    }
}

Per altre informazioni, vedere Registrazione in .NET Core 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 famosa 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).
  • 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 Web

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 è {radice contenuto}/wwwroot. Specificare una radice Web diversa impostandone il percorso durante la compilazione dell'host. Per altre informazioni, vedere Web root (Radice Web).

Impedire la pubblicazione di file in wwwroot con l'elemento di progetto <Content> nel file di progetto. L'esempio seguente impedisce la pubblicazione di contenuto in wwwroot/local e nelle 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.

Risorse aggiuntive

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.

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.
  • Viene definita la pipeline di gestione delle richieste dell'app come una serie di componenti middleware.

Il codice di avvio dell'app seguente supporta:

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

Inserimento di dipendenze (servizi)

ASP.NET Core include l'inserimento delle dipendenze che rende disponibili i servizi configurati in un'app. I servizi vengono aggiunti al contenitore di inserimento delle dipendenze con WebApplicationBuilder.Services, builder.Services nel codice precedente. Quando viene creata un'istanza di WebApplicationBuilder, vengono aggiunti molti servizi forniti dal framework. 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 evidenziato precedente, builder include configurazione, registrazione e molti altri servizi aggiunti al contenitore di inserimento delle dipendenze.

Il codice seguente aggiunge Razor Pages, controller MVC con visualizzazioni e un oggetto personalizzato DbContext al contenitore di inserimento delle dipendenze:

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

I servizi vengono in genere risolti dall'inserimento delle dipendenze tramite l'inserimento del costruttore. Il framework di inserimento delle dipendenze fornisce un'istanza di questo servizio in fase di esecuzione.

Il codice seguente usa l'inserimento del costruttore per risolvere il contesto del database e il logger dall'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();
    }
}

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}. Il middleware aggiunto all'app è evidenziato nel codice seguente:

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

Per altre informazioni, vedere Middleware ASP.NET Core.

Host

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

  • Un'implementazione del server HTTP
  • I componenti middleware
  • Registrazione
  • Servizi di inserimento delle dipendenze
  • Impostazione

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

I ASP.NET Core WebApplication e i tipi sono consigliati e WebApplicationBuilder 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.

Nell'esempio seguente viene creata un'istanza di WebApplication:

var builder = WebApplication.CreateBuilder(args);

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

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.
  • Inviare l'output di registrazione alla console e ai provider di debug.

Scenari non Web

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

Server

Un'app ASP.NET Core usa un'implementazione del server HTTP per l'ascolto delle richieste HTTP. Il server espone le richieste all'app sotto forma di insieme di funzionalità di richiesta strutturate in un HttpContext.

ASP.NET Core include le implementazioni server seguenti:

  • Kestrel è un server Web multipiattaforma. Kestrel viene spesso eseguito in una configurazione con 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.

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

Impostazione

ASP.NET Core offre un framework di configurazione che ottiene le impostazioni, ad esempio 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 la lettura 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, .NET Core offre Secret Manager. Per i segreti di produzione, si consiglia di usare Azure Key Vault.

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

Ambienti

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:

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

Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.

Registrazione

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
  • Azure App Service
  • Azure Application Insights

Per creare i log, risolvere un servizio ILogger<TCategoryName> dall'inserimento delle dipendenze e chiamare metodi di registrazione, come LogInformation. Ad esempio:

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

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

Routing

Una route è un modello URL di cui è stato eseguito il mapping su un gestore. Il gestore è in genere una pagina Razor, un metodo di azione in un controller MVC o un middleware. Il routing di ASP.NET Core consente di controllare gli URL usati dall'app.

Il codice seguente, generato dal modello di applicazione Web ASP.NET Core, chiama 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();

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

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 famosa 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).
  • 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 Web

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 è {radice contenuto}/wwwroot. Specificare una radice Web diversa impostandone il percorso durante la compilazione dell'host. Per altre informazioni, vedere Web root (Radice Web).

Impedire la pubblicazione di file in wwwroot con l'elemento di progetto <Content> nel file di progetto. L'esempio seguente impedisce la pubblicazione di contenuto in wwwroot/local e nelle 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.

Risorse aggiuntive

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.

Classe Startup

All'interno della classe Startup:

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

Ecco un esempio di classe 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();
        });
    }
}

Per altre informazioni, vedere Avvio delle app in ASP.NET Core.

Inserimento di dipendenze (servizi)

ASP.NET Core include un framework di inserimento delle dipendenze predefinito che rende disponibili i servizi configurati pe un'app. Ad esempio, un componente di registrazione è un servizio.

Il codice per configurare o registrare i servizi viene aggiunto al metodo Startup.ConfigureServices. Ad esempio:

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

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

I servizi vengono in genere risolti dall'inserimento delle dipendenze tramite l'inserimento del costruttore. Con l'inserimento del costruttore, una classe dichiara un parametro del costruttore del tipo richiesto o di un'interfaccia. Il framework di inserimento delle dipendenze fornisce un'istanza di questo servizio in fase di esecuzione.

Nell'esempio seguente viene usato l'inserimento del costruttore per risolvere un RazorPagesMovieContext dall'inserimento delle dipendenze:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;

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

    // ...

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

Se il contenitore di inversione del controllo (IoC, Inversion of Control) predefinito non soddisfa tutte le esigenze di un'app, è possibile usare invece un contenitore IoC di terze parti.

Per altre informazioni, vedere Inserimento 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... nel metodo Startup.Configure. Per abilitare il rendering dei file statici, ad esempio, chiamare UseStaticFiles.

L'esempio seguente configura una pipeline di gestione delle richieste:

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

    app.UseRouting();

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

ASP.NET Core include un'ampia gamma di middleware predefinito. È anche possibile scrivere componenti middleware personalizzati.

Per altre informazioni, vedere Middleware ASP.NET Core.

Host

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

  • Un'implementazione del server HTTP
  • I componenti middleware
  • Registrazione
  • Servizi di inserimento delle dipendenze
  • Impostazione

Esistono due host diversi:

  • Host generico .NET
  • Host Web ASP.NET Core

È consigliabile usare l'host generico .NET. L'host Web ASP.NET Core è disponibile solo per compatibilità con le versioni precedenti.

L'esempio seguente crea un host generico .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>();
            });
}

I metodi CreateDefaultBuilder e ConfigureWebHostDefaults configurano 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, appsettings.{Environment}.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.

Per altre informazioni, vedere Host generico .NET in ASP.NET Core.

Scenari non Web

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

Server

Un'app ASP.NET Core usa un'implementazione del server HTTP per l'ascolto delle richieste HTTP. Il server espone le richieste all'app sotto forma di insieme di funzionalità di richiesta strutturate in un HttpContext.

ASP.NET Core include le implementazioni server seguenti:

  • Kestrel è un server Web multipiattaforma. Kestrel viene spesso eseguito in una configurazione con 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.

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

Impostazione

ASP.NET Core offre un framework di configurazione che ottiene le impostazioni, ad esempio 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 la lettura 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.

Il modo preferito per leggere i valori di configurazione correlati prevede l'uso del modello di opzioni. Per altre informazioni, vedere Associare dati di configurazione gerarchici usando il modello di opzioni.

Per la gestione dei dati di configurazione riservati, ad esempio le password, .NET Core offre Secret Manager. Per i segreti di produzione, si consiglia di usare Azure Key Vault.

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

Ambienti

Gli ambienti di esecuzione, ad esempio Development, Staging e Production, sono un concetto fondamentale in ASP.NET Core. 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 viene configurata l'app per fornire informazioni dettagliate sugli errori durante l'esecuzione nell'ambiente 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();
    });
}

Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.

Registrazione

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
  • Azure App Service
  • Azure Application Insights

Per creare i log, risolvere un servizio ILogger<TCategoryName> dall'inserimento delle dipendenze e chiamare metodi di registrazione, come LogInformation. Ad esempio:

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

I metodi di registrazione come LogInformation supportano qualsiasi numero di campi. Questi campi vengono comunemente usati per costruire un messaggio string, ma alcuni provider di registrazione li inviano a un archivio dati come campi separati. Questa funzionalità consente ai provider di registrazione di implementare la registrazione semantica, nota anche come registrazione strutturata.

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

Routing

Una route è un modello URL di cui è stato eseguito il mapping su un gestore. Il gestore è in genere una pagina Razor, un metodo di azione in un controller MVC o un middleware. Il routing di ASP.NET Core consente di controllare gli URL usati dall'app.

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

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 famosa 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).
  • 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 Web

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 è {radice contenuto}/wwwroot. Specificare una radice Web diversa impostandone il percorso durante la compilazione dell'host. Per altre informazioni, vedere Web root (Radice Web).

Impedire la pubblicazione di file in wwwroot con l'elemento di progetto <Content> nel file di progetto. L'esempio seguente impedisce la pubblicazione di contenuto in wwwroot/local e nelle relative sottodirectory:

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

Nei file Razor.cshtml, il carattere tilde-barra (~/) punta alla radice Web. Un percorso che inizia con ~/ viene definito percorso virtuale.

Per altre informazioni, vedere File statici in 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 Blazor indicazioni fondamentali, che aggiunge o sostituisce le linee guida in questo nodo, vedere Blazor base.

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.
  • Viene definita la pipeline di gestione delle richieste dell'app come una serie di componenti middleware.

Il codice di avvio dell'app seguente supporta:

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

Inserimento di dipendenze (servizi)

ASP.NET Core include l'inserimento delle dipendenze che rende disponibili i servizi configurati in un'app. I servizi vengono aggiunti al contenitore di inserimento delle dipendenze con WebApplicationBuilder.Services, builder.Services nel codice precedente. Quando viene creata un'istanza di WebApplicationBuilder, vengono aggiunti molti servizi forniti dal framework. 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 evidenziato precedente, builder include configurazione, registrazione e molti altri servizi aggiunti al contenitore di inserimento delle dipendenze.

Il codice seguente aggiunge Razor Pages, controller MVC con visualizzazioni e un oggetto personalizzato DbContext al contenitore di inserimento delle dipendenze:

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

I servizi vengono in genere risolti dall'inserimento delle dipendenze tramite l'inserimento del costruttore. Il framework di inserimento delle dipendenze fornisce un'istanza di questo servizio in fase di esecuzione.

Il codice seguente usa l'inserimento del costruttore per risolvere il contesto del database e il logger dall'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();
    }
}

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}. Il middleware aggiunto all'app è evidenziato nel codice seguente:

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

Per altre informazioni, vedere Middleware ASP.NET Core.

Host

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

  • Un'implementazione del server HTTP
  • I componenti middleware
  • Registrazione
  • Servizi di inserimento delle dipendenze
  • Impostazione

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

I ASP.NET Core WebApplication e i tipi sono consigliati e WebApplicationBuilder 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.

Nell'esempio seguente viene creata un'istanza di WebApplication:

var builder = WebApplication.CreateBuilder(args);

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

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.
  • Inviare l'output di registrazione alla console e ai provider di debug.

Scenari non Web

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

Server

Un'app ASP.NET Core usa un'implementazione del server HTTP per l'ascolto delle richieste HTTP. Il server espone le richieste all'app sotto forma di insieme di funzionalità di richiesta strutturate in un HttpContext.

ASP.NET Core include le implementazioni server seguenti:

  • Kestrel è un server Web multipiattaforma. Kestrel viene spesso eseguito in una configurazione con 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.

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

Impostazione

ASP.NET Core offre un framework di configurazione che ottiene le impostazioni, ad esempio 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 la lettura 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, .NET Core offre Secret Manager. Per i segreti di produzione, si consiglia di usare Azure Key Vault.

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

Ambienti

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:

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

Per altre informazioni, vedere Usare più ambienti in ASP.NET Core.

Registrazione

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
  • Azure App Service
  • Azure Application Insights

Per creare i log, risolvere un servizio ILogger<TCategoryName> dall'inserimento delle dipendenze e chiamare metodi di registrazione, come LogInformation. Ad esempio:

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

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

Routing

Una route è un modello URL di cui è stato eseguito il mapping su un gestore. Il gestore è in genere una pagina Razor, un metodo di azione in un controller MVC o un middleware. Il routing di ASP.NET Core consente di controllare gli URL usati dall'app.

Il codice seguente, generato dal modello di applicazione Web ASP.NET Core, chiama 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();

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

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 famosa 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).
  • 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 Web

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 è {radice contenuto}/wwwroot. Specificare una radice Web diversa impostandone il percorso durante la compilazione dell'host. Per altre informazioni, vedere Web root (Radice Web).

Impedire la pubblicazione di file in wwwroot con l'elemento di progetto <Content> nel file di progetto. L'esempio seguente impedisce la pubblicazione di contenuto in wwwroot/local e nelle 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.

Risorse aggiuntive