Avvio di ASP.NET Core Blazor

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

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

• serverper un'app Blazor Server
• webassemblyper un'app Blazor WebAssembly

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:

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.

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

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)

• 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)
• Layout di distribuzione per le app ospitate Blazor WebAssembly ASP.NET Core
• App di test di base nel repository GitHub per ASP.NET Core (BasicTestApp.lib.module.js)

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.

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:

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:

Nel file Program:

In Startup.Configure di Startup.cs:

Sviluppo sul lato client senza eseguire la pre-gestione

Passare StaticFileOptions a MapFallbackToFile che specifica le intestazioni di risposta nella OnPrepareResponse fase.

Nel file lato Program server:

In Startup.Configure di Startup.cs:

var staticFileOptions = new StaticFileOptions
{
    OnPrepareResponse = context =>
    {
        context.Context.Response.Headers.Append("Content-Security-Policy", 
            "{POLICY STRING}");
    }
};

...

app.MapFallbackToFile("index.html", staticFileOptions);

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

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.

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>

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.