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 Blazor script (blazor.*.js), dove il * segnaposto è:

• web per un oggetto Blazor Web App
• serverper un'app Blazor Server
• webassemblyper un'app Blazor WebAssembly

Per la posizione dello script, vedere ASP.NET Struttura del progetto CoreBlazor.

Per avviare Blazormanualmente :

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> .
• Posizionare le opzioni di rendering statico lato server (SSR statico) nella ssr proprietà .
• Posizionare le opzioni sul lato BlazorSignalR server nella circuit proprietà .
• Posizionare le opzioni WebAssembly sul lato client nella webAssembly proprietà .

<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 ASP.NET Struttura del progetto CoreBlazor.

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'app 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 dell'avvio Blazor Web App . Ad esempio, beforeWebStart viene usato per personalizzare il processo di caricamento, il livello di registrazione e altre opzioni. Riceve le Blazor opzioni Web (options).
• afterWebStarted(blazor): Chiamato dopo che tutte le beforeWebStart promesse si risolvono. Ad esempio, afterWebStarted può essere usato per registrare Blazor listener 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 Blazor Serverle app , Blazor WebAssemblye 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.
  • Lato server, beforeStart riceve le opzioni di SignalR avvio del circuito (options).
  • In , BlazorWebViewnon 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).

Callback aggiuntivi 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 Promiseoggetto e la promessa è attesa prima che l'avvio continui.

Per il nome del file:

• Se gli JS inizializzatori vengono utilizzati come asset statici nel progetto, usare il formato {ASSEMBLY NAME}.lib.module.js, dove il {ASSEMBLY NAME} segnaposto è 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, usare il formato {LIBRARY NAME/PACKAGE ID}.lib.module.js, dove il segnaposto è il nome della libreria o l'identificatore {LIBRARY NAME/PACKAGE ID} del pacchetto del progetto. Ad esempio, assegnare 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 prima e dopo l'avvio Blazor Web App di 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 completino l'esecuzione prima dell'avvio Blazor .

Per Blazor Serverle app , Blazor WebAssemblye Blazor Hybrid :

Nell'esempio seguente vengono illustrati gli JS inizializzatori che caricano script personalizzati prima e dopo Blazor l'avvio <head> aggiungendoli a 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 completino l'esecuzione prima dell'avvio Blazor .

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:

• 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)
• ASP.NET gestione degli eventi core Blazor (esempio di evento Incolla appunti personalizzato)
• Abilitare la generazione di codice a matrice per le app di autenticazione TOTP in un 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 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).

Verificare che le librerie vengano caricate in un ordine specifico

Aggiungere script personalizzati a <head> in 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 ASP.NET Struttura del progetto CoreBlazor.

Concatenare l'oggetto Promise risultante da un avvio manuale

Per eseguire attività aggiuntive, ad esempio JS l'inizializzazione dell'interoperabilità, usare then per concatenare i Promise risultati 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 ASP.NET Struttura del progetto CoreBlazor.

Nota

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

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 e assembly .NET
• Dati specifici delle impostazioni locali

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 fetch richiesta a un nuovo nome.

Nota

Le origini esterne devono restituire le intestazioni CORS (Cross-Origin Resource Sharing) necessarie per consentire il caricamento delle risorse tra le origini nei browser. 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 ASP.NET Struttura del progetto CoreBlazor.

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 ASP.NET Struttura del progetto CoreBlazor.

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 altre informazioni, vedere ASP.NET Runtime .NET Core Blazor WebAssembly e memorizzazione nella cache del bundle dell'app.

Intestazioni di controllo nel codice C#

Controllare le intestazioni all'avvio nel codice C# usando gli approcci seguenti.

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.

Scenari lato server e lato client prerendered

Usare ASP.NET Core Middleware per controllare l'insieme 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 altre informazioni, vedere Scrivere middleware personalizzato ASP.NET Core.

Per altre informazioni sui provider di servizi di configurazione, vedere Applicare criteri di sicurezza del contenuto per ASP.NET Core Blazor.

Indicatori di stato del caricamento lato client

Un indicatore di stato del caricamento mostra lo stato di avanzamento del caricamento dell'app agli utenti, a indicare che l'app viene caricata normalmente e che l'utente deve attendere il completamento del caricamento.

Blazor Web App stato di caricamento

L'indicatore di stato 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 stato di caricamento non è consigliabile per i componenti WebAssembly interattivi perché Blazor Web Appi componenti lato client prerendere sul server per 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.
• Inavvertitamente rimuovendo il contenuto prerisorso durante il caricamento del runtime .NET WebAssembly.

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

Creare un LoadingProgress componente nell'app .Client che chiama OperatingSystem.IsBrowser:

• Quando false, visualizzare un indicatore di stato di caricamento mentre il Blazor bundle viene scaricato e prima che il Blazor runtime venga attivato nel client.
• Quando true, eseguire il rendering del contenuto del componente richiesto.

La dimostrazione seguente usa l'indicatore di stato di caricamento trovato nelle app create dal Blazor WebAssembly modello, inclusa una modifica degli stili forniti dal modello. Gli stili vengono caricati nel contenuto dell'app <head> dal HeadContent componente. Per altre informazioni, vedere Controllare il contenuto head nelle app ASP.NET CoreBlazor.

LoadingProgress.razor:

@if (!OperatingSystem.IsBrowser())
{
    <HeadContent>
        <style>
            .loading-progress {
                position: relative;
                display: block;
                width: 8rem;
                height: 8rem;
                margin: 20vh auto 1rem auto;
            }

                .loading-progress circle {
                    fill: none;
                    stroke: #e0e0e0;
                    stroke-width: 0.6rem;
                    transform-origin: 50% 50%;
                    transform: rotate(-90deg);
                }

                    .loading-progress circle:last-child {
                        stroke: #1b6ec2;
                        stroke-dasharray: 
                            calc(3.142 * var(--blazor-load-percentage, 0%) * 0.8), 
                            500%;
                        transition: stroke-dasharray 0.05s ease-in-out;
                    }

            .loading-progress-text {
                position: relative;
                text-align: center;
                font-weight: bold;
                top: -90px;
            }

                .loading-progress-text:after {
                    content: var(--blazor-load-percentage-text, "Loading");
                }

            code {
                color: #c02d76;
            }
        </style>
    </HeadContent>
    <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>
}
else
{
    @ChildContent
}

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

In un componente che adotta il rendering Interactive WebAssembly eseguire il wrapping del markup del Razor componente con il LoadingProgress componente. 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>

<LoadingProgress>
    <h1>Counter</h1>

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

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

@code {
    private int currentCount = 0;

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

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 stato round predefinito viene implementato in HTML nel wwwroot/index.html file:

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

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 configureRuntime funzione con il dotnet generatore host di runtime 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 ASP.NET Struttura del progetto CoreBlazor.
• 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 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).

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 dei moduli, impostare su disableDomPreservation true per Blazor.start:

<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 ASP.NET Struttura del progetto CoreBlazor.

Risorse aggiuntive

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