Avvio di ASP.NET Core Blazor

Questo articolo illustra la configurazione di avvio dell'app Blazor .

Per indicazioni generali sulla configurazione dell'app core ASP.NET per lo sviluppo sul lato server, vedere Configurazione in ASP.NET Core.

Processo di avvio e configurazione

Il Blazor processo di avvio è automatico e asincrono tramite lo script Blazor (blazor.*.js), dove il segnaposto * è:

• web per un oggetto Blazor Web App
• server per un'app Blazor Server
• webassembly per un'app Blazor WebAssembly

Per la posizione dello script, vedere struttura del progetto ASP.NET Core.

Per avviare Blazor manualmente:

Blazor Web App:

• Aggiungere un attributo e un autostart="false" valore al Blazor<script> tag.
• Inserire uno script che chiama Blazor.start() dopo il Blazor<script> tag e all'interno del tag di chiusura </body> .
• Nella proprietà ssr, posizionare le opzioni di rendering statico lato server (SSR statico).
• Posizionare le opzioni del circuito lato server nella proprietà Blazor.
• Posizionare le opzioni WebAssembly client nella proprietà webAssembly.

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  ...
  Blazor.start({
    ssr: {
      ...
    },
    circuit: {
      ...
    },
    webAssembly: {
      ...
    }
  });
  ...
</script>

Autonomo Blazor WebAssembly e Blazor Server:

• Aggiungere un attributo e un autostart="false" valore al Blazor<script> tag.
• Inserire uno script che chiama Blazor.start() dopo il Blazor<script> tag e all'interno del tag di chiusura </body> .
• È possibile fornire opzioni aggiuntive nel Blazor.start() parametro .

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  ...
  Blazor.start({
    ...
  });
  ...
</script>

Nell'esempio precedente il {BLAZOR SCRIPT} segnaposto è il percorso dello script e il Blazor nome del file. Per la posizione dello script, vedere struttura del progetto ASP.NET Core.

Inizializzatori JavaScript

Gli inizializzatori JavaScript (JS) eseguono la logica prima e dopo il caricamento di un'app Blazor. Gli inizializzatori JS sono utili negli scenari seguenti:

• Personalizzazione del caricamento di un'applicazione Blazor.
• Inizializzazione delle librerie prima dell'avvio di Blazor.
• Configurazione delle impostazioni di Blazor.

JS gli inizializzatori vengono rilevati come parte del processo di compilazione e importati automaticamente. L'uso degli inizializzatori JS spesso elimina la necessità di attivare manualmente le funzioni di script dall'app quando si usano le librerie di classi Razor (RCL, Razor Class Library).

Per definire un inizializzatore JS, aggiungere un modulo JS al progetto denominato {NAME}.lib.module.js, dove il segnaposto {NAME} è il nome dell'assembly, il nome della libreria o l'identificatore del pacchetto. Inserire il file nella radice Web del progetto, che è in genere la cartella wwwroot.

Per Blazor Web Apps:

• beforeWebStart(options): Chiamato prima che Blazor Web App inizi. Ad esempio, beforeWebStart viene usato per personalizzare il processo di caricamento, il livello di registrazione e altre opzioni. Riceve le opzioni del Web Blazor (options).
• afterWebStarted(blazor): Chiamato dopo che tutte le beforeWebStart promesse sono state risolte. Ad esempio, afterWebStarted può essere usato per registrare Blazor ascoltatori di eventi e tipi di evento personalizzati. L'istanza Blazor viene passata a afterWebStarted come argomento (blazor).
• beforeServerStart(options, extensions): Chiamato prima dell'avvio del primo runtime del server. Riceve le SignalR opzioni di avvio del circuito (options) e tutte le estensioni (extensions) aggiunte durante la pubblicazione.
• afterServerStarted(blazor): Chiamato dopo l'avvio del primo runtime di Interactive Server.
• beforeWebAssemblyStart(options, extensions): Chiamato prima dell'avvio del runtime Interactive WebAssembly. Riceve le Blazor opzioni (options) e le eventuali estensioni (extensions) aggiunte durante la pubblicazione. Le opzioni, ad esempio, possono specificare l'uso di un caricatore di risorse di avvio personalizzato.
• afterWebAssemblyStarted(blazor): Chiamato dopo l'avvio del runtime Interactive WebAssembly.

Nota

Gli inizializzatori legacy JS (beforeStart, afterStarted) non vengono richiamati per impostazione predefinita in un oggetto Blazor Web App. È possibile abilitare gli inizializzatori legacy per l'esecuzione con l'opzione enableClassicInitializers . Tuttavia, l'esecuzione dell'inizializzatore legacy è imprevedibile.

<script>
  Blazor.start({ enableClassicInitializers: true });
</script>

Per le app Blazor Server, Blazor WebAssembly e Blazor Hybrid:

• beforeStart(options, extensions): chiamata prima dell'avvio di Blazor. beforeStart, ad esempio, viene usata per personalizzare il processo di caricamento, il livello di registrazione e altre opzioni specifiche del modello di hosting.
  • Lato client, beforeStart riceve le Blazor opzioni () e le eventuali estensioni (optionsextensions) aggiunte durante la pubblicazione. Le opzioni, ad esempio, possono specificare l'uso di un caricatore di risorse di avvio personalizzato.
  • Sul lato server, beforeStart riceve le opzioni di avvio circuito SignalR (options).
  • In un BlazorWebView, non vengono passate opzioni.
• afterStarted(blazor): chiamata dopo che Blazor è pronto a ricevere le chiamate da JS. afterStarted, ad esempio, viene usato per inizializzare le librerie effettuando le chiamate all'interoperabilità JS e registrando gli elementi personalizzati. L'istanza Blazor viene passata a afterStarted come argomento (blazor).

Richiamate aggiuntive del runtime .NET WebAssembly:

• onRuntimeConfigLoaded(config): chiamato quando viene scaricata la configurazione di avvio. Consente all'app di modificare i parametri (config) prima dell'avvio del runtime (il parametro è MonoConfig da dotnet.d.ts):

  export function onRuntimeConfigLoaded(config) {
    // Sample: Enable startup diagnostic logging when the URL contains 
    // parameter debug=1
    const params = new URLSearchParams(location.search);
    if (params.get("debug") == "1") {
      config.diagnosticTracing = true;
    }
  }
  

• onRuntimeReady({ getAssemblyExports, getConfig }): Chiamato dopo l'avvio del runtime WebAssembly .NET (il parametro è RuntimeAPI da dotnet.d.ts):

  export function onRuntimeReady({ getAssemblyExports, getConfig }) {
    // Sample: After the runtime starts, but before Main method is called, 
    // call [JSExport]ed method.
    const config = getConfig();
    const exports = await getAssemblyExports(config.mainAssemblyName);
    exports.Sample.Greet();
  }
  

Entrambi i callback possono restituire un Promise, e la promessa è attesa prima che l'avvio continui.

Per il nome del file:

• Se gli JS inizializzatori sono utilizzati come risorsa statica nel progetto, usa il formato {ASSEMBLY NAME}.lib.module.js, dove il segnaposto {ASSEMBLY NAME} rappresenta il nome dell'assembly dell'app. Ad esempio, assegnare al file il nome BlazorSample.lib.module.js per un progetto con il nome di assembly BlazorSample. Inserire il file nella cartella wwwroot dell'app.
• Se gli JS inizializzatori vengono utilizzati da un RCL, utilizzare il formato {LIBRARY NAME/PACKAGE ID}.lib.module.js, dove il segnaposto {LIBRARY NAME/PACKAGE ID} indica il nome della libreria o l'identificatore del pacchetto del progetto (<PackageId> valore nel file di progetto della libreria). Ad esempio, assegna al file il nome RazorClassLibrary1.lib.module.js per una libreria RCL con l'identificatore del pacchetto RazorClassLibrary1. Inserire il file nella cartella wwwroot della libreria.

Per Blazor Web Apps:

Nell'esempio seguente vengono illustrati gli JS inizializzatori che caricano script personalizzati sia prima sia dopo l'inizio di Blazor Web App, aggiungendoli a <head> in beforeWebStart e afterWebStarted.

export function beforeWebStart() {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'beforeStartScripts.js');
  document.head.appendChild(customScript);
}

export function afterWebStarted() {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'afterStartedScripts.js');
  document.head.appendChild(customScript);
}

L'esempio precedente beforeWebStart garantisce solo che lo script personalizzato venga caricato prima Blazor dell'avvio. Non garantisce che le promesse attese nello script ne completino l'esecuzione prima che Blazor inizi.

Per le app Blazor Server, Blazor WebAssembly e Blazor Hybrid:

Nell'esempio seguente vengono illustrati gli JS inizializzatori che caricano script personalizzati prima dell'inizio e dopo l'inizio di Blazor, aggiungendoli al <head> in beforeStart e afterStarted.

export function beforeStart(options, extensions) {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'beforeStartScripts.js');
  document.head.appendChild(customScript);
}

export function afterStarted(blazor) {
  var customScript = document.createElement('script');
  customScript.setAttribute('src', 'afterStartedScripts.js');
  document.head.appendChild(customScript);
}

L'esempio precedente beforeStart garantisce solo che lo script personalizzato venga caricato prima Blazor dell'avvio. Non garantisce che le promesse attese nello script ne completino l'esecuzione prima che Blazor inizi.

Nota

Le app MVC e Razor Pages non caricano automaticamente gli inizializzatori JS. Il codice dello sviluppatore può tuttavia includere uno script per recuperare il manifesto dell'app e attivare il carico degli inizializzatori JS.

Per esempi di JS inizializzatori, vedere le risorse seguenti:

• Blazor Web App indicatore di caricamento (Esempio di rendering WebAssembly interattivo globale senza prerendering)
• ASP.NET Core Blazor JavaScript con rendering statico lato server (SSR statico)
• Usare Razor i componenti nelle app JavaScript e nei framework SPA (quoteContainer2 esempio)
• Gestione degli eventi di ASP.NET Core (Esempio di evento di incolla dagli appunti personalizzato)
• Abilitare la generazione di codice QR per le app di autenticazione TOTP in un'app ASP.NET Core Blazor Web App
• App di test di base nel repository GitHub per ASP.NET Core (BasicTestApp.lib.module.js)

Nota

I collegamenti della documentazione alla sorgente di riferimento .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo attuale della prossima versione di .NET. Per selezionare un tag per una versione specifica, utilizzare l'elenco a discesa Passa tra rami o tag. 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).

Verificare che le librerie vengano caricate in un ordine specifico

Aggiungere script personalizzati a <head>, beforeStart e afterStarted nell'ordine in cui devono essere caricati.

L'esempio seguente carica script1.js prima script2.js e script3.js prima script4.jsdi :

export function beforeStart(options, extensions) {
    var customScript1 = document.createElement('script');
    customScript1.setAttribute('src', 'script1.js');
    document.head.appendChild(customScript1);

    var customScript2 = document.createElement('script');
    customScript2.setAttribute('src', 'script2.js');
    document.head.appendChild(customScript2);
}

export function afterStarted(blazor) {
    var customScript1 = document.createElement('script');
    customScript1.setAttribute('src', 'script3.js');
    document.head.appendChild(customScript1);

    var customScript2 = document.createElement('script');
    customScript2.setAttribute('src', 'script4.js');
    document.head.appendChild(customScript2);
}

Importare moduli aggiuntivi

Usare istruzioni di primo livello import nel JS file di inizializzatori per importare moduli aggiuntivi.

additionalModule.js:

export function logMessage() {
  console.log('logMessage is logging');
}

JS Nel file di inizializzatori (.lib.module.js):

import { logMessage } from "/additionalModule.js";

export function beforeStart(options, extensions) {
  ...

  logMessage();
}

Importa mappa

Le mappe di importazione sono supportate da ASP.NET Core e Blazor.

Inizializzare Blazor quando il documento è pronto

L'esempio seguente inizia Blazor quando il documento è pronto:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    Blazor.start();
  });
</script>

Nell'esempio precedente il {BLAZOR SCRIPT} segnaposto è il percorso dello script e il Blazor nome del file. Per la posizione dello script, vedere struttura del progetto ASP.NET Core.

Concatenare al Promise che risulta da un avvio manuale

Per eseguire attività aggiuntive, ad esempio JS l'inizializzazione dell'interoperabilità, usare then per collegarsi al Promise che risulta da un avvio manuale Blazor dell'app:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start().then(function () {
    ...
  });
</script>

Nell'esempio precedente il {BLAZOR SCRIPT} segnaposto è il percorso dello script e il Blazor nome del file. Per la posizione dello script, vedere struttura del progetto ASP.NET Core.

Nota

Affinché una libreria esegui automaticamente attività aggiuntive dopo Blazor l'avvio, usare un inizializzatore JavaScript. L'uso di un JS inizializzatore non richiede all'utente della libreria di concatenare le chiamate all'avvio manuale di JS.

Caricare le risorse di avvio sul lato client

Quando un'app viene caricata nel browser, l'app scarica le risorse di avvio dal server:

• Codice JavaScript per avviare l'app
• Runtime .NET e assembly
• Dati specifici del locale

Personalizzare il modo in cui queste risorse di avvio vengono caricate usando l'API loadBootResource . La loadBootResource funzione esegue l'override del meccanismo di caricamento delle risorse di avvio predefinito. Usare loadBootResource per gli scenari seguenti:

• Caricare risorse statiche, ad esempio i dati del fuso orario o dotnet.wasm, da una rete CDN.
• Caricare assembly compressi usando una richiesta HTTP e decomprimerli nel client per gli host che non supportano il recupero di contenuti compressi dal server.
• Eseguire l'alias delle risorse in un nome diverso reindirizzando ogni richiesta fetch a un nuovo nome.

Nota

Le fonti esterne devono restituire le intestazioni Cross-Origin Resource Sharing (CORS) necessarie affinché i browser consentano il caricamento cross-origin delle risorse. Le reti CDN in genere forniscono le intestazioni necessarie.

loadBootResource i parametri vengono visualizzati nella tabella seguente.

Parametro	Descrizione
type	Tipo di risorsa. I tipi consentiti includono: assembly, pdbdotnetjs, dotnetwasm, e timezonedata. È sufficiente specificare i tipi per i comportamenti personalizzati. I tipi non specificati in loadBootResource vengono caricati dal framework in base ai relativi comportamenti di caricamento predefiniti. La dotnetjs risorsa di avvio (dotnet.*.js) deve restituire null per il comportamento di caricamento predefinito o un URI per l'origine della dotnetjs risorsa di avvio.
name	Nome della risorsa.
defaultUri	URI relativo o assoluto della risorsa.
integrity	Stringa di integrità che rappresenta il contenuto previsto nella risposta.

La loadBootResource funzione può restituire una stringa URI per eseguire l'override del processo di caricamento. Nell'esempio seguente i file seguenti da bin/Release/{TARGET FRAMEWORK}/wwwroot/_framework vengono gestiti da una rete CDN in https://cdn.example.com/blazorwebassembly/{VERSION}/:

• dotnet.*.js
• dotnet.wasm
• Dati del fuso orario

Il {TARGET FRAMEWORK} segnaposto è il moniker del framework di destinazione , ad esempio net7.0. Il {VERSION} segnaposto è la versione del framework condiviso , ad esempio 7.0.0.

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        console.log(`Loading: '${type}', '${name}', '${defaultUri}', '${integrity}'`);
        switch (type) {
          case 'dotnetjs':
          case 'dotnetwasm':
          case 'timezonedata':
            return `https://cdn.example.com/blazorwebassembly/{VERSION}/${name}`;
        }
      }
    }
  });
</script>

Blazor WebAssembly autonomo:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      console.log(`Loading: '${type}', '${name}', '${defaultUri}', '${integrity}'`);
      switch (type) {
        case 'dotnetjs':
        case 'dotnetwasm':
        case 'timezonedata':
          return `https://cdn.example.com/blazorwebassembly/{VERSION}/${name}`;
      }
    }
  });
</script>

Nell'esempio precedente il {BLAZOR SCRIPT} segnaposto è il percorso dello script e il Blazor nome del file. Per la posizione dello script, vedere struttura del progetto ASP.NET Core.

Per personalizzare più degli URL per le risorse di avvio, la loadBootResource funzione può chiamare fetch direttamente e restituire il risultato. Nell'esempio seguente viene aggiunta un'intestazione HTTP personalizzata alle richieste in uscita. Per mantenere il comportamento di controllo dell'integrità predefinito, passare attraverso il integrity parametro .

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      loadBootResource: function (type, name, defaultUri, integrity) {
        if (type == 'dotnetjs') {
          return null;
        } else {
          return fetch(defaultUri, {
            cache: 'no-cache',
            integrity: integrity,
            headers: { 'Custom-Header': 'Custom Value' }
          });
        }
      }
    }
  });
</script>

Blazor WebAssembly autonomo:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    loadBootResource: function (type, name, defaultUri, integrity) {
      if (type == 'dotnetjs') {
        return null;
      } else {
        return fetch(defaultUri, {
          cache: 'no-cache',
          integrity: integrity,
          headers: { 'Custom-Header': 'Custom Value' }
        });
      }
    }
  });
</script>

Nell'esempio precedente il {BLAZOR SCRIPT} segnaposto è il percorso dello script e il Blazor nome del file. Per la posizione dello script, vedere struttura del progetto ASP.NET Core.

Quando la loadBootResource funzione restituisce null, Blazor usa il comportamento di caricamento predefinito per la risorsa. Ad esempio, il codice precedente restituisce null per la dotnetjs risorsa di avvio (dotnet.*.js) perché la dotnetjs risorsa di avvio deve restituire null per il comportamento di caricamento predefinito o un URI per l'origine della dotnetjs risorsa di avvio.

La loadBootResource funzione può anche restituire una Response promessa. Per un esempio, vedere Ospitare e distribuire ASP.NET Core Blazor WebAssembly.

Per ulteriori informazioni, vedere ASP.NET Core: errori di memorizzazione nella cache e controllo dell'integritàBlazor WebAssembly.

Gestire le intestazioni nel codice C#

Controlla le intestazioni all'avvio nel codice C# utilizzando i seguenti approcci.

Negli esempi seguenti un CSP (Content Security Policy) viene applicato all'app tramite un'intestazione CSP. Il {POLICY STRING} segnaposto è la stringa di criteri CSP. Per ulteriori informazioni sui CSP (Criteri di Sicurezza del Contenuto), vedere Applicare un criterio di sicurezza del contenuto per ASP.NET Core Blazor.

Nota

Le intestazioni non possono essere configurate dopo che la risposta è iniziata. Gli approcci in questa sezione impostano solo le intestazioni prima dell'avvio della risposta, quindi gli approcci descritti di seguito sono sicuri. Per altre informazioni, vedere IHttpContextAccessor/HttpContext nelle app ASP.NET Core Blazor.

Scenari lato server e lato client pre-renderizzati

Usare ASP.NET Core Middleware per controllare la collezione di intestazioni.

Nel file Program:

app.Use(async (context, next) =>
{
    context.Response.Headers.Append("Content-Security-Policy", "{POLICY STRING}");
    await next();
});

L'esempio precedente usa il middleware inline, ma è anche possibile creare una classe middleware personalizzata e chiamare il middleware con un metodo di estensione nel Program file. Per ulteriori informazioni, consultare Sviluppare middleware personalizzato ASP.NET Core.

Indicatori di caricamento sul lato client

Un indicatore di caricamento indica che l'app viene caricata normalmente e che l'utente deve attendere il completamento del caricamento.

Blazor Web App indicatore di caricamento

L'indicatore di caricamento usato nelle Blazor WebAssembly app non è presente in un'app creata dal modello di Blazor Web App progetto. In genere, un indicatore di caricamento non è consigliabile per i componenti WebAssembly interattivi perché i componenti lato client vengono prerenderizzati sul server per assicurare tempi di caricamento iniziali rapidi. Per le situazioni in modalità di rendering misto, il framework o il codice per sviluppatori deve prestare attenzione anche per evitare i problemi seguenti:

• Visualizzazione di più indicatori di caricamento nella stessa pagina sottoposta a rendering.
• Eliminare inavvertitamente il contenuto pre-renderizzato durante il caricamento del runtime .NET WebAssembly.

Una versione futura di .NET potrebbe fornire un indicatore di caricamento basato su framework. Nel frattempo, è possibile aggiungere un indicatore di caricamento personalizzato a un oggetto Blazor Web App.

Rendering interattivo di componente WebAssembly con prerendering

Questo scenario si applica al rendering interattivo di WebAssembly basato sui componenti (@rendermode InteractiveWebAssembly applicato ai singoli componenti).

Creare un componente ContentLoading nella cartella Layout dell'app .Client che chiama OperatingSystem.IsBrowser:

• Quando viene visualizzato false, mostra un indicatore di caricamento.
• Quando true, eseguire il rendering del contenuto del componente richiesto.

Per caricare gli stili CSS per l'indicatore, aggiungere al contenuto <head> gli stili con il componente HeadContent. Per ulteriori informazioni, vedere Blazor.

Layout/ContentLoading.razor:

@if (!RendererInfo.IsInteractive)
{
    <!-- OPTIONAL ...
    <HeadContent>
        <style>
            ...
        </style>
    </HeadContent>
    -->
    <progress id="loadingIndicator" aria-label="Content loading…"></progress>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

Se nel progetto non esiste già una cartella Layout, aggiungi il namespace della cartella .Client al file Layout. Nell'esempio seguente lo spazio dei nomi del progetto è BlazorSample.Client:

@using BlazorSample.Client.Layout

In un componente che adotta il rendering Interactive WebAssembly, incapsulare il markup del componente Razor col componente ContentLoading. L'esempio seguente illustra l'approccio con il Counter componente di un'app creata dal Blazor Web App modello di progetto.

Pages/Counter.razor:

@page "/counter"
@rendermode InteractiveWebAssembly

<PageTitle>Counter</PageTitle>

<ContentLoading>
    <h1>Counter</h1>

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

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

@code {
    private int currentCount = 0;

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

Rendering globale interattivo di WebAssembly con prerendering

Questo scenario si applica al rendering WebAssembly interattivo globale con prerendering (@rendermode="InteractiveWebAssembly" sui componenti HeadOutlet e Routes nel componente App).

Creare un componente ContentLoading nella cartella Layout dell'app .Client che chiama RendererInfo.IsInteractive:

• Quando viene visualizzato false, mostra un indicatore di caricamento.
• Quando true, eseguire il rendering del contenuto del componente richiesto.

Per caricare gli stili CSS per l'indicatore, aggiungere al contenuto <head> gli stili con il componente HeadContent. Per ulteriori informazioni, vedere Blazor.

Layout/ContentLoading.razor:

@if (!RendererInfo.IsInteractive)
{
    <!-- OPTIONAL ...
    <HeadContent>
        <style>
            ...
        </style>
    </HeadContent>
    -->
    <progress id="loadingIndicator" aria-label="Content loading…"></progress>
}
else
{
    @ChildContent
}

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }
}

Se nel progetto non esiste già una cartella Layout, aggiungi il namespace della cartella .Client al file Layout. Nell'esempio seguente lo spazio dei nomi del progetto è BlazorSample.Client:

@using BlazorSample.Client.Layout

Nel componente MainLayout (Layout/MainLayout.razor) del progetto .Client, incapsula la proprietà Body (@Body) con il componente ContentLoading.

In Layout/MainLayout.razor:

+ <ContentLoading>
    @Body
+ </ContentLoading>

Elaborazione WebAssembly interattiva globale senza prerendering

Questo scenario si applica al rendering globale interattivo di WebAssembly senza prerendering (@rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" e HeadOutlet sui componenti e Routes nel componente App).

Aggiungere un inizializzatore JavaScript all'app. Nell'esempio di nome file del modulo JavaScript seguente, il {ASSEMBLY NAME} segnaposto è il nome dell'assembly del progetto server , ad esempio BlazorSample. La cartella wwwroot in cui si trova il modulo è la cartella wwwroot nel progetto sul lato server, non nel progetto .Client.

L'esempio seguente usa un progress indicatore che non indica lo stato effettivo di recapito delle risorse di avvio sul lato client al client, ma funge da approccio generale per un ulteriore sviluppo se si vuole che l'indicatore di stato mostri lo stato effettivo di caricamento delle risorse di avvio dell'app.

wwwroot/{ASSEMBLY NAME}.lib.module.js:

export function beforeWebStart(options) {
  var progress = document.createElement("progress");
  progress.id = 'loadingIndicator';
  progress.ariaLabel = 'Blazor loading…';
  progress.style = 'position:absolute;top:50%;left:50%;margin-right:-50%;' +
    'transform:translate(-50%,-50%);';
  document.body.appendChild(progress);
}

export function afterWebAssemblyStarted(blazor) {
  var progress = document.getElementById('loadingIndicator');
  progress.remove();
}

Blazor WebAssembly stato di caricamento dell'app

Il modello di progetto contiene indicatori SVG (Scalable Vector Graphics) e text che mostrano lo stato di avanzamento del caricamento dell'app.

Gli indicatori di stato vengono implementati con HTML e CSS usando due proprietà personalizzate CSS (variabili) fornite da Blazor:

• --blazor-load-percentage: percentuale di file dell'app caricati.
• --blazor-load-percentage-text: percentuale di file dell'app caricati, arrotondata al numero intero più vicino.

Usando le variabili CSS precedenti, è possibile creare indicatori di stato personalizzati corrispondenti allo stile dell'app.

Nell'esempio seguente :

• resourcesLoaded è un conteggio istantaneo delle risorse caricate durante l'avvio dell'app.
• totalResources è il numero totale di risorse da caricare.

const percentage = resourcesLoaded / totalResources * 100;
document.documentElement.style.setProperty(
  '--blazor-load-percentage', `${percentage}%`);
document.documentElement.style.setProperty(
  '--blazor-load-percentage-text', `"${Math.floor(percentage)}%"`);

L'indicatore di avanzamento circolare predefinito viene implementato in HTML nel file wwwroot/index.html.

<div id="app">
    <svg class="loading-progress">
        <circle r="40%" cx="50%" cy="50%" />
        <circle r="40%" cx="50%" cy="50%" />
    </svg>
    <div class="loading-progress-text"></div>
</div>

Per esaminare il markup e lo stile del modello di progetto per gli indicatori di stato predefiniti, vedere l'origine di riferimento ASP.NET Core:

• wwwroot/index.html
• app.css

Nota

I collegamenti della documentazione alla sorgente di riferimento .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo attuale della prossima versione di .NET. Per selezionare un tag per una versione specifica, utilizzare l'elenco a discesa Passa tra rami o tag. 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).

Anziché usare l'indicatore di stato round predefinito, nell'esempio seguente viene illustrato come implementare un indicatore di stato lineare.

Aggiungere gli stili seguenti a wwwroot/css/app.css:

.linear-progress {
    background: silver;
    width: 50vw;
    margin: 20% auto;
    height: 1rem;
    border-radius: 10rem;
    overflow: hidden;
    position: relative;
}

.linear-progress:after {
    content: '';
    position: absolute;
    inset: 0;
    background: blue;
    scale: var(--blazor-load-percentage, 0%) 100%;
    transform-origin: left top;
    transition: scale ease-out 0.5s;
}

Una variabile CSS (var(...)) viene usata per passare il valore di --blazor-load-percentage alla scale proprietà di uno pseudoelemento blu che indica lo stato di avanzamento del caricamento dei file dell'app. Quando l'app viene caricata, --blazor-load-percentage viene aggiornata automaticamente, che modifica dinamicamente la rappresentazione visiva dell'indicatore di stato.

In wwwroot/index.htmlrimuovere l'indicatore rotondo SVG predefinito in <div id="app">...</div> e sostituirlo con il markup seguente:

<div class="linear-progress"></div>

Configurare il runtime .NET WebAssembly

Negli scenari di programmazione avanzati, la funzione configureRuntime con il builder dell'host di runtime dotnet viene usata per configurare il runtime .NET WebAssembly. Ad esempio, dotnet.withEnvironmentVariable imposta una variabile di ambiente che:

• Configura il runtime .NET WebAssembly.
• Modifica il comportamento di una libreria C.

Nota

Una richiesta di documentazione è in sospeso nel dotnet/runtime repository GitHub per altre informazioni sulle variabili di ambiente che configurano il runtime WebAssembly .NET o influiscono sul comportamento delle librerie C. Anche se la richiesta di documentazione è in sospeso, sono disponibili altre informazioni e collegamenti incrociati a risorse aggiuntive nella richiesta, domanda/richiesta per la documentazione in .NET WASM runtime env vars (dotnet/runtime #98225).

La configureRuntime funzione può essere usata anche per abilitare l'integrazione con un profiler del browser.

Per i segnaposto negli esempi seguenti che impostano una variabile di ambiente:

• Il {BLAZOR SCRIPT} segnaposto è il percorso dello script e il Blazor nome del file. Per la posizione dello script, vedere struttura del progetto ASP.NET Core.
• Il {NAME} segnaposto è il nome della variabile di ambiente.
• Il {VALUE} segnaposto è il valore della variabile di ambiente.

Blazor Web App:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    webAssembly: {
      configureRuntime: dotnet => {
        dotnet.withEnvironmentVariable("{NAME}", "{VALUE}");
      }
    }
  });
</script>

Blazor WebAssembly autonomo:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    configureRuntime: dotnet => {
      dotnet.withEnvironmentVariable("{NAME}", "{VALUE}");
    }
  });
</script>

Nota

È possibile accedere all'istanza di runtime .NET usando l'API runtime .NET WebAssembly (Blazor.runtime). Ad esempio, la configurazione di compilazione dell'app può essere ottenuta usando Blazor.runtime.runtimeBuildInfo.buildConfiguration.

Per altre informazioni sulla configurazione del runtime .NET WebAssembly, vedere il file di definizione TypeScript del runtime (dotnet.d.ts) nel dotnet/runtime repository GitHub.

Nota

I collegamenti della documentazione alla sorgente di riferimento .NET in genere caricano il ramo predefinito del repository, che rappresenta lo sviluppo attuale della prossima versione di .NET. Per selezionare un tag per una versione specifica, utilizzare l'elenco a discesa Passa tra rami o tag. 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).

Disabilitare la navigazione avanzata e la gestione dei moduli

Questa sezione si applica a Blazor Web Apps.

Per disabilitare la navigazione avanzata e la gestione avanzata dei moduli, impostare su disableDomPreservation per true:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>
<script>
  Blazor.start({
    ssr: { disableDomPreservation: true }
  });
</script>

Nell'esempio precedente il {BLAZOR SCRIPT} segnaposto è il percorso dello script e il Blazor nome del file. Per la posizione dello script, vedere struttura del progetto ASP.NET Core.

Risorse aggiuntive

• Ambienti: impostare l'ambiente dell'app
• SignalR (include sezioni sulla SignalR configurazione di avvio)
• Globalizzazione e localizzazione: impostare in modo statico la cultura con Blazor.start() (solo lato client)
• Blazor WebAssembly compressione