Nozioni fondamentali su ASP.NET Core Blazor

Articolo
09/23/2024

Nota

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

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere Criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 8 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 8 di questo articolo.

Gli articoli sulle nozioni fondamentali offrono linee guida sui principali concetti di Blazor. Alcuni dei concetti richiedono una conoscenza di base dei componenti di Razor, che vengono descritti ulteriormente nella sezione successiva di questo articolo e trattati in dettaglio negli articoli sui componenti.

Concetti relativi al rendering statico e interattivo

Razoril rendering dei componenti viene eseguito in modo statico o interattivo.

Il rendering statico o statico è uno scenario lato server che indica che il rendering del componente viene eseguito senza la capacità di interazione tra l'utente e il codice .NET/C#. Gli eventi DOM JavaScript e HTML rimangono invariati, ma non è possibile elaborare eventi utente nel client con .NET in esecuzione nel server.

Il rendering interattivo o interattivo significa che il componente ha la capacità di elaborare gli eventi .NET tramite codice C#. Gli eventi .NET vengono elaborati nel server dal runtime di ASP.NET Core o nel browser nel client dal runtime basato su Blazor WebAssembly.

Importante

Quando si usa un Blazor Web App, la maggior parte dei componenti di esempio della Blazor documentazione richiede interattività per funzionare e dimostrare i concetti trattati negli articoli. Quando si testa un componente di esempio fornito da un articolo, assicurarsi che l'app adotta interattività globale o che il componente adotta una modalità di rendering interattiva.

Altre informazioni su questi concetti e su come controllare il rendering statico e interattivo sono disponibili nell'articolo ASP.NET Core Blazor render modes più avanti nella Blazor documentazione.

Concetti relativi al rendering di client e server

In tutta la Blazor documentazione, l'attività che viene eseguita nel sistema dell'utente viene detto che si verifica sul lato client o sul lato client. L'attività che viene eseguita su un server viene in genere eseguita sul server o sul lato server.

Il termine rendering significa produrre il markup HTML visualizzato dai browser.

Il rendering sul lato client indica che il markup HTML finale viene generato dal runtime .NET WebAssembly nel client. Nessun codice HTML per l'interfaccia utente generata dal client dell'app viene inviato da un server al client per questo tipo di rendering. Si presuppone che l'interattività dell'utente con la pagina. Non esiste un concetto simile al rendering lato client statico . Si presuppone che csr sia interattivo, quindi "rendering lato client interattivo " e "CSR interattivo " non vengono usati dal settore o nella Blazor documentazione.
Il rendering lato server (SSR) indica che il markup HTML finale viene generato dal runtime di ASP.NET Core nel server. Il codice HTML viene inviato al client tramite una rete per la visualizzazione dal browser del client. Nessun codice HTML per l'interfaccia utente generata dal server dell'app viene creato dal client per questo tipo di rendering. SSR può essere di due varietà:
- SSR statico: il server produce codice HTML statico che non fornisce interattività utente o mantiene Razor lo stato del componente.
- SSR interattivo: Blazor gli eventi consentono l'interattività degli utenti e Razor lo stato del Blazor componente vengono gestiti dal framework.
Il prerendering è il processo di rendering iniziale del contenuto della pagina nel server senza abilitare i gestori eventi per i controlli di cui è stato eseguito il rendering. Il server restituisce l'interfaccia utente HTML della pagina appena possibile in risposta alla richiesta iniziale, che rende l'app più reattiva agli utenti. Il prerendering può anche migliorare l'ottimizzazione del motore di ricerca (SEO) eseguendo il rendering del contenuto per la risposta HTTP iniziale usata dai motori di ricerca per calcolare la classificazione delle pagine. Il prerendering è sempre seguito dal rendering finale, nel server o nel client.

Componenti di Razor

Le app Blazor si basano sui componenti di Razor, spesso chiamati semplicemente componenti. Un componente è un elemento dell'interfaccia utente, ad esempio una pagina, una finestra di dialogo o un modulo per l'immissione di dati. I componenti sono classi .NET C# compilati in assembly .NET.

Razor si riferisce al modo in cui i componenti sono solitamente scritti sotto forma di pagina di markup Razor per la logica e la composizione dell'interfaccia utente lato client. Razor è una sintassi per la combinazione di markup HTML con codice C# progettata per la produttività degli sviluppatori. I file Razor usano l'estensione .razor.

Anche se alcuni sviluppatori Blazor e risorse online usano il termine "componenti di Blazor", nella documentazione non è così e viene in genere usato il termine "componenti di Razor" o "componenti".

La documentazione di Blazor adotta diverse convenzioni per illustrare e descrivere i componenti:

In genere, gli esempi rispettano le convenzioni di codifica ASP.NET Core/C# e le linee guida di progettazione. Per altre informazioni, vedere le risorse seguenti:
- linee guida di progettazione del framework di base ASP.NET (dotnet/aspnetcore repository GitHub)
- Convenzioni di codifica C# (guida a C#)
Il codice del progetto, i percorsi e i nomi dei file, i nomi dei modelli di progetto e altri termini specializzati sono in inglese (Stati Uniti) e in genere sono isolati nel codice.
Ai componenti si fa in genere riferimento con il nome della classe C# (notazione Pascal) seguito dalla parola "component". Ad esempio, "FileUpload component" fa riferimento a un componente tipico per il caricamento di file.
In genere, il nome della classe C# di un componente è uguale al nome file.
I componenti instradabili in genere impostano gli URL relativi sul nome della classe del componente nella notazione kebab. Ad esempio, un componente FileUpload include la configurazione di routing per raggiungere il componente sottoposto a rendering nell'URL relativo /file-upload. Il routing e l'esplorazione sono trattati in Routing ed esplorazione in ASP.NET Core Blazor.
Quando vengono usate più versioni di un componente, vengono numerate in sequenza. Ad esempio, il FileUpload3 componente viene raggiunto in /file-upload-3.
Razor Le direttive all'inizio di una definizione di componente (.razor file) vengono inserite nell'ordine seguente: @page, @rendermode (.NET 8 o versione successiva), @using istruzioni, altre direttive in ordine alfabetico.
Sebbene non sia necessario per private i membri, i modificatori di accesso vengono usati negli esempi di articoli e nelle app di esempio. Ad esempio, private viene indicato per dichiarare un campo denominato maxAllowedFiles come private int maxAllowedFiles = 3;.
I valori dei parametri del componente portano con un Razor simbolo riservato@, ma non è obbligatorio. I valori letterali (ad esempio, valori booleani), le parole chiave (ad esempio this, ) e null come valori dei parametri del componente non sono preceduti da @, ma si tratta anche di una convenzione di documentazione. Se lo si desidera, il codice può anteporre ai valori letterali @ .
Le classi C# usano la this parola chiave ed evitano il prefisso dei campi con un carattere di sottolineatura (_) assegnato a nei costruttori, che differiscono dalle linee guida di progettazione del framework di base ASP.NET.
Negli esempi che usano costruttori primari (C# 12 o versione successiva) i parametri del costruttore primario vengono in genere usati direttamente dai membri della classe.

Altre informazioni sulla Razor sintassi dei componenti sono disponibili nella sezione relativa alla Razor sintassi dei componenti principali di ASP.NETRazor.

Quello che segue è un componente contatore di esempio e una parte di un'app creata da un modello di progetto Blazor. La trattazione dettagliata dei componenti è disponibile negli articoli sui componenti più avanti nella documentazione. L'esempio seguente illustra i concetti relativi ai componenti visti negli articoli sulle nozioni fondamentali prima di arrivare agli articoli sui componenti più avanti nella documentazione.

Counter.razor:

Il componente presuppone che una modalità di rendering interattiva venga ereditata da un componente padre o applicata a livello globale all'app.

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

Il componente presuppone che una modalità di rendering interattiva venga ereditata da un componente padre o applicata a livello globale all'app.

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

Il componente Counter precedente:

Imposta la route con la direttiva @page nella prima riga.
Imposta il titolo e l'intestazione della pagina.
Esegue il rendering del conteggio corrente con @currentCount. currentCount è una variabile intera definita nel codice C# del blocco @code.
Visualizza un pulsante per attivare il metodo IncrementCount, che è disponibile anche nel blocco @code e aumenta il valore della variabile currentCount.

Modalità di rendering

Gli articoli nel nodo Concetti fondamentali fanno riferimento al concetto di modalità di rendering. Questo argomento è trattato in dettaglio nell'articolo ASP.NET Modalità di rendering core Blazor nel nodo Componenti, visualizzato dopo il nodo Nozioni fondamentali degli articoli.

Per i riferimenti iniziali in questo nodo di articoli per il rendering dei concetti relativi alla modalità di rendering, tenere presente quanto segue in questo momento:

Ogni componente in un Blazor Web App oggetto adotta una modalità di rendering per determinare il modello di hosting usato, dove viene eseguito il rendering e se viene eseguito o meno il rendering statico nel server, il rendering con per l'interattività dell'utente nel server o il rendering per l'interattività dell'utente nel client (in genere con prerendering sul server).

Blazor Server e Blazor WebAssembly le app per le versioni di ASP.NET Core precedenti a .NET 8 rimangono risolte nei concetti del modello di hosting, non nelle modalità di rendering. Le modalità di rendering vengono applicate concettualmente a Blazor Web Apps in .NET 8 o versioni successive.

La tabella seguente illustra le modalità di rendering disponibili per i componenti di rendering Razor in un oggetto Blazor Web App. Le modalità di rendering vengono applicate ai componenti con la @rendermode direttiva sull'istanza del componente o sulla definizione del componente. È anche possibile impostare una modalità di rendering per l'intera app.

Nome	Descrizione	Posizione di rendering	Interattivo
Server statico	Rendering statico lato server (SSR statico)	Server	No
Server interattivo	Rendering lato server interattivo (SSR interattivo) con Blazor Server	Server	Sì
WebAssembly interattivo	Rendering lato client (CSR) con Blazor WebAssembly†	Client	Sì
Auto interattivo	SSR interattivo che usa Blazor Server inizialmente e quindi csr nelle visite successive dopo il download del Blazor bundle	Server, quindi client	Sì

si presuppone che il rendering lato client (CSR) † sia interattivo. "Rendering lato client interattivo " e "CSR interattivo " non vengono usati dal settore o nella Blazor documentazione.

Le informazioni precedenti sulle modalità di rendering sono tutte le informazioni necessarie per comprendere gli articoli sui nodi Fundamentals . Se non si ha familiarità Blazor con gli articoli e si legge Blazor in ordine verso il basso il sommario, è possibile ritardare l'utilizzo di informazioni dettagliate sulle modalità di rendering fino a raggiungere l'articolo sulle modalità di rendering di ASP.NET Core Blazor nel nodo Componenti.

DOM (Document Object Model)

I riferimenti al modello a oggetti documento usano l'abbreviazione DOM.

Per ulteriori informazioni, vedi le seguenti risorse:

Subset di API .NET per Blazor WebAssembly le app

Un elenco curato di API .NET specifiche supportate nel browser per Blazor WebAssembly non è disponibile. È tuttavia possibile cercare manualmente un elenco di API .NET annotate con [UnsupportedOSPlatform("browser")] per individuare le API .NET non supportate in WebAssembly.

Nota

I collegamenti della documentazione all'origine del riferimento .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo corrente per la versione successiva di .NET. Per selezionare un tag per una versione specifica, usare l'elenco a discesa Switch branches or tags. Per altre informazioni, vedere How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Come selezionare un tag di versione del codice sorgente di ASP.NET - dotnet/AspNetCore.Docs #26205).

Per ulteriori informazioni, vedi le seguenti risorse:

App di esempio

Le app di esempio della documentazione sono disponibili per la consultazione e il download:

Blazor repository GitHub di esempi (dotnet/blazor-samples)

Individuare un'app di esempio selezionando prima la cartella della versione corrispondente alla versione di .NET con cui si sta lavorando.

Il repository di esempio contiene due tipi di esempi:

Le app di esempio di frammento di codice forniscono gli esempi di codice visualizzati negli articoli. Queste app vengono compilate ma non sono necessariamente eseguibili. Queste app sono utili solo per ottenere codice di esempio visualizzato negli articoli.
App di esempio per compilare ed eseguire articoli associati Blazor per gli scenari seguenti:
- Blazor Server con EF Core
- Blazor Server e Blazor WebAssembly con SignalR
- Registrazione abilitata per gli ambiti Blazor WebAssembly

Per altre informazioni e un elenco degli esempi nel repository, vedere il Blazor repository GitHub di esempi README.md file.

L'app di test di base del repository ASP.NET Core è anche un set utile di esempi per diversi Blazor scenari:

BasicTestApp nell'origine di riferimento di ASP.NET Core (dotnet/aspnetcore)

Nota

Per scaricare le app di esempio:

Scaricare il file ZIP del Blazor repository di esempi.
Decomprimere il file .

Byte multiple

Le dimensioni dei byte .NET usano prefissi delle metriche per i multipli non decimali di byte in base alle potenze di 1024.

Nome (abbreviazione)	Dimensione	Esempio
Kilobyte (KB)	1.024 byte	1 KB = 1.024 byte
Megabyte (MB)	1.024² byte	1 MB = 1.048.576 byte
Gigabyte (GB)	1.024³ byte	1 GB = 1.073.741.824 byte

Richieste di supporto

Solo i problemi correlati alla documentazione sono appropriati per il repository dotnet/AspNetCore.Docs. Per il supporto al prodotto, non aprire un problema relativo alla documentazione. Richiedere assistenza tramite uno o più dei canali di supporto seguenti:

Per un potenziale bug nel framework o per feedback sul prodotto, aprire un problema per l'unità del prodotto ASP.NET Core nei problemi relativi a dotnet/aspnetcore. I report sui bug in genere richiedono quanto segue:

Spiegazione chiara del problema: seguire le istruzioni nel modello di problema GitHub fornito dall'unità del prodotto quando si apre il problema.
Progetto minimo della procedura di riproduzione: inserire un progetto in GitHub che i tecnici dell'unità del prodotto possano scaricare ed eseguire. Inserire un commento incrociato al progetto nel commento di apertura del problema.

Per un potenziale problema con un articolo su Blazor, aprire un problema di documentazione. Per aprire un problema di documentazione, usare il collegamento Open a documentation issue feedback (Apri un problema di documentazione) nella parte inferiore dell'articolo. I metadati aggiunti al problema forniscono dati di rilevamento e esegue automaticamente il ping dell'autore dell'articolo. Se l'argomento è stato discusso con l'unità prodotto prima di aprire il problema della documentazione, inserire un collegamento incrociato al problema di progettazione nel commento di apertura del problema della documentazione.

Per problemi o commenti e suggerimenti su Visual Studio, usare i movimenti Segnala un problema o Suggerisci una funzionalità da Visual Studio, che apre problemi interni per Visual Studio. Per altre informazioni vedere Feedback di Visual Studio.

Per problemi relativi a Visual Studio Code, chiedere supporto nei forum di supporto della community. Per i report sui bug e il feedback sul prodotto, aprire un problema nel microsoft/vscode repository GitHub.

I problemi di GitHub per la documentazione su Blazor vengono contrassegnati automaticamente per la valutazione nel progetto Blazor.Docs (repository GitHub di dotnet/AspNetCore.Docs). Attendere un breve periodo di tempo per ricevere una risposta, soprattutto nei fine settimana e nei giorni festivi. In genere, gli autori della documentazione rispondono entro 24 ore nei giorni feriali.

Collegamenti della community alle risorse di Blazor

Per una raccolta di collegamenti alle risorse di Blazor gestite dalla community, visitare Awesome Blazor.

Nota

Microsoft non è proprietaria né gestisce o supporta Awesome Blazor e la maggior parte dei prodotti e dei servizi della community descritti e disponibili tramite collegamento.

Condividi tramite

Nozioni fondamentali su ASP.NET Core Blazor

Concetti relativi al rendering statico e interattivo

Concetti relativi al rendering di client e server

Componenti di Razor

Modalità di rendering

DOM (Document Object Model)

Subset di API .NET per Blazor WebAssembly le app

App di esempio

Byte multiple

Richieste di supporto

Collegamenti della community alle risorse di Blazor

Risorse aggiuntive