Nozioni fondamentali su ASP.NET Core Blazor

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 di client e server

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

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

• Rendering lato client (CSR) indica che il markup HTML finale viene generato dal runtime .NET WebAssembly sul 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. L'interattività dell'utente con la pagina è presunta. Non esiste il concetto di 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à per l'utente né mantiene lo stato del componente.
  • SSR interattivo: Blazor gli eventi consentono l'interattività degli utenti e Razor lo stato del Blazor componente è gestito dal framework.

• Il "prerendering" è il processo di rendering iniziale del contenuto della pagina sul server senza abilitare i gestori di eventi per i controlli già eseguiti. 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 Razor

Le app Blazor si basano su componenti 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 lingua inglese degli Stati Uniti e di solito sono racchiusi in blocchi di 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 generalmente impostano gli URL relativi sul nome della classe del componente in kebab-case. 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 la navigazione sono trattati in ASP.NET Core Routing e navigazioneBlazor.
• Quando vengono usate più versioni di un componente, vengono numerate in sequenza. Ad esempio, il componente FileUpload3 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 iniziano con un 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. Il proprio codice può anteporre ai letterali @ se lo si desidera.
• Le classi C# usano la this parola chiave ed evitano di anteporre un carattere di sottolineatura (_) ai campi ai quali si assegna nei costruttori, il che differisce dalle linee guida di progettazione del framework ASP.NET Core.
• 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. Negli esempi di articolo le righe di codice vengono suddivise per ridurre lo scorrimento orizzontale. Queste interruzioni non influiscono sull'esecuzione, ma possono essere rimosse quando vengono incollate nel tuo progetto.

Altre informazioni sulla sintassi dei componenti Razor sono disponibili nella sezione Razor sintassi dei componenti ASP.NET CoreRazor.

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:

@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"

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

DOM (Document Object Model)

I riferimenti al Document Object Model (Modello a Oggetti di Documento) usano l'abbreviazione DOM.

Per ulteriori informazioni, vedi le seguenti risorse:

• Introduzione al DOM (documentazione mdn)
• Specifica del modello a oggetti documento di livello 1 (W3C)

Subset di API .NET per le app Blazor WebAssembly

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.

Per ulteriori informazioni, vedi le seguenti risorse:

• Librerie di classi: analizzatore della compatibilità del browser sul lato client
• Annotare le API come non supportate in piattaforme specifiche (dotnet/designs repository GitHub

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.

Per ulteriori informazioni, un elenco degli esempi e le istruzioni per il download, consulta il file README del repository GitHub degli esempi Blazor.

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)

Multipli di byte

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

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:

• Stack Overflow (tag: blazor)
• Team Slack generale di ASP.NET Core
• Blazor Gitter

Per un potenziale bug nel framework o per fornire feedback sul prodotto, aprire una segnalazione per l'unità del prodotto ASP.NET Core nella sezione dotnet/aspnetcore issues. 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 per la riproduzione: pubblicare un progetto su GitHub che gli ingegneri dell'unità di prodotto possano scaricare ed eseguire. Collegare il progetto al commento di apertura dell'issue.

Per un potenziale problema con un articolo su Blazor, apri una segnalazione 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 tracciamento e eseguono 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.