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 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 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. 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 Razor sintassi dei componenti sono disponibili nella sezione relativa alla Razor sintassi dei componentiRazorASP.NET.

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 modello a oggetti 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 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.

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

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.

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