ASP.NET Core, nozioni di base, panoramica

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 ASP.NET Nozioni fondamentali di baseBlazor.

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:

• Razor Pages
• Controller MVC con visualizzazioni
• API Web con controller
• API Web minime

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:

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

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.

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

• Codice sorgente di WebApplicationBuilder

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:

• Razor Pages
• Controller MVC con visualizzazioni
• API Web con controller
• API Web minime

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:

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

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.

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

• Codice sorgente di WebApplicationBuilder

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.

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.