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.

Windows

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.

macOS

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

Linux

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

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