Démarrage ASP.NET Core Blazor

Cet article explique la configuration de démarrage de l’application Blazor.

Pour des conseils généraux sur la configuration des applications ASP.NET Core pour le développement côté serveur, consultez Configuration dans ASP.NET Core.

Processus de démarrage et configuration

Le processus de démarrage Blazor est automatique et asynchrone par le script Blazor (blazor.*.js), où l’espace réservé * est :

• web pour une Blazor Web App
• server pour une application Blazor Server
• webassembly pour une application Blazor WebAssembly

Pour connaître l’emplacement du script, consultez ASP.NET Core Blazor structure du projet.

Pour démarrer Blazor manuellement :

Blazor Web App :

• Ajoutez un attribut et une valeur autostart="false" à la balise Blazor<script>.
• Placez un script qui appelle Blazor.start() après la balise Blazor<script> et à l’intérieur de la balise fermante </body>.
• Placez les options de rendu statique côté serveur (SSR statique) dans la propriété ssr.
• Placez les options côté serveur du circuit Blazor-SignalR dans la propriété circuit.
• Placez les options WebAssembly côté client dans la propriété webAssembly.

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

Blazor WebAssembly et Blazor Server autonomes :

• Ajoutez un attribut et une valeur autostart="false" à la balise Blazor<script>.
• Placez un script qui appelle Blazor.start() après la balise Blazor<script> et à l’intérieur de la balise fermante </body>.
• Vous pouvez fournir des options supplémentaires dans le paramètre Blazor.start().

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

Dans l’exemple précédent, l’espace réservé {BLAZOR SCRIPT} est le chemin d’accès de script Blazor et le nom de fichier. Pour connaître l’emplacement du script, consultez ASP.NET Core Blazor structure du projet.

Initialiseurs JavaScript

Les initialiseurs JavaScript (JS) exécutent la logique avant et après le chargement d’une application Blazor. Les initialiseurs JS sont utiles dans les scénarios suivants :

• Personnalisation de la façon dont une application Blazor se charge.
• Initialisation des bibliothèques avant le démarrage de Blazor.
• Configuration des paramètres Blazor.

Les initialiseurs JS sont détectés dans le cadre du processus de génération et importés automatiquement. L’utilisation des initialiseurs JS supprime souvent la nécessité de déclencher manuellement des fonctions de script à partir de l’application lors de l’utilisation de bibliothèques de classes (RCL) Razor.

Pour définir un initialiseur JS, ajoutez un module JS au projet nommé {NAME}.lib.module.js, où l’espace réservé {NAME} est le nom de l’assembly, le nom de la bibliothèque ou l’identificateur de package. Placez le fichier dans la racine web du projet, qui est généralement le dossier wwwroot.

Pour des Blazor Web App :

• beforeWebStart(options) : appelée avant le démarrage de Blazor Web App. Par exemple, beforeWebStart est utilisé pour personnaliser le processus de chargement, le niveau de journalisation et d'autres options. Reçoit les options Web Blazor (options).
• afterWebStarted(blazor) : appelé après la résolution de toutes les promesses beforeWebStart. Par exemple, afterWebStarted peut être utilisé pour enregistrer des écouteurs d’événements Blazor et des types d’événements personnalisés. L’instance Blazor est passée à afterWebStarted en tant qu’argument (blazor).
• beforeServerStart(options, extensions) : appelé avant le démarrage du premier runtime du serveur. Reçoit les options de démarrage du circuit (SignalR) et toutes les extensions ajoutées (options) lors de la publication.
• afterServerStarted(blazor) : appelé après le démarrage du premier runtime du serveur interactif.
• beforeWebAssemblyStart(options, extensions) : appelé avant le démarrage du runtime Interactive WebAssembly. Reçoit les Blazor options (options) et toutes les extensions (extensions) ajoutées lors de la publication. Par exemple, les options peuvent spécifier l’utilisation d’un chargeur de ressources de démarrage personnalisé.
• afterWebAssemblyStarted(blazor) : appelé après le démarrage du runtime Interactive WebAssembly.

Remarque

Les initialiseurs JS hérités (beforeStart, afterStarted) ne sont pas appelés par défaut dans une Blazor Web App. Vous pouvez activer l’exécution des initialiseurs hérités avec l’option enableClassicInitializers. Toutefois, l’exécution d’un initialisateur hérité est imprévisible.

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

En raison d’un bogue de framework dans .NET 8 et 9 (dotnet/aspnetcore #54049), le Blazor script doit être démarré manuellement quand beforeWebAssemblyStart(options, extensions) ou afterWebAssemblyStarted(blazor) sont appelés. Si l'application serveur ne démarre pas encore Blazor manuellement avec une configuration WebAssembly (webAssembly: {...}), mettez à jour le composant App dans le projet serveur en suivant ces étapes.

Dans Components/App.razor, supprimez la balise existante Blazor<script> :

- <script src="_framework/blazor.web.js"></script>

Remplacez la balise <script> par le balisage suivant qui commence Blazor manuellement par une configuration WebAssembly (webAssembly: {...}) :

<script src="_framework/blazor.web.js" autostart="false"></script>
<script>
    Blazor.start({
        webAssembly: {}
    });
</script>

Les applications Blazor Server, Blazor WebAssembly et Blazor Hybrid :

• beforeStart(options, extensions) : appelée avant le démarrage de Blazor. Par exemple, beforeStart est utilisée pour personnaliser le processus de chargement, le niveau de journalisation et d’autres options spécifiques au modèle d’hébergement.
  • Côté client, beforeStart reçoit les Blazor options (options) et toutes les extensions (extensions) ajoutées lors de la publication. Par exemple, les options peuvent spécifier l’utilisation d’un chargeur de ressources de démarrage personnalisé.
  • Côté serveur, beforeStart reçoit les SignalR options de démarrage du circuit (options).
  • Dans un BlazorWebView, aucune option n’est transmise.
• afterStarted(blazor) : appelée une fois que Blazor est prêt à recevoir des appels à partir de JS. Par exemple, afterStarted permet d’initialiser des bibliothèques en effectuant des appels d’interopérabilité JS et en inscrivant des éléments personnalisés. L’instance Blazor est passée à afterStarted en tant qu’argument (blazor).

Rappels de runtime .NET WebAssembly supplémentaires :

• onRuntimeConfigLoaded(config) est appelée lorsque la configuration de démarrage est téléchargée. Permet à l’application de modifier des paramètres (configuration) avant le démarrage du runtime (le paramètre est MonoConfig depuis 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 }) est appelée après le démarrage du runtime .NET WebAssembly (le paramètre est RuntimeAPI depuis 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();
  }
  

Les deux rappels peuvent retourner une Promise, et la promesse est attendue avant que le démarrage ne continue.

Pour le nom de fichier :

• Si les initialiseurs JS sont consommés en tant que ressource statique dans le projet, utilisez le format {ASSEMBLY NAME}.lib.module.js, où l’espace réservé {ASSEMBLY NAME} est le nom de l’assembly de l’application. Par exemple, nommez le fichier BlazorSample.lib.module.js pour un projet avec le nom d’assembly BlazorSample. Placez le fichier dans le dossier wwwroot de l’application.
• Si les initialiseurs JS sont consommés à partir d’une RCL, utilisez le format {LIBRARY NAME/PACKAGE ID}.lib.module.js, où l’espace réservé {LIBRARY NAME/PACKAGE ID} est le nom de la bibliothèque ou l’identificateur de package du projet. Par exemple, nommez le fichier RazorClassLibrary1.lib.module.js pour une bibliothèque RCL avec l’identificateur de package RazorClassLibrary1. Placez le fichier dans le dossier wwwroot de la bibliothèque.

Pour des Blazor Web App :

L’exemple suivant illustre des initialiseurs JS qui chargent des scripts personnalisés avant et après le démarrage de Blazor Web App en les ajoutant au <head> dans beforeWebStart et 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’exemple beforeWebStart précédent garantit uniquement que le script personnalisé se charge avant le démarrage de Blazor. Il ne garantit pas que les promesses attendues dans le script terminent leur exécution avant que Blazor commence.

Les applications Blazor Server, Blazor WebAssembly et Blazor Hybrid :

L’exemple suivant illustre des initialiseurs JS qui chargent des scripts personnalisés avant et après le début de Blazor en les ajoutant au <head> dans beforeStart et 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’exemple beforeStart précédent garantit uniquement que le script personnalisé se charge avant le démarrage de Blazor. Il ne garantit pas que les promesses attendues dans le script terminent leur exécution avant que Blazor commence.

Remarque

Les applications MVC et Razor Pages ne chargent pas automatiquement les initialiseurs JS. Toutefois, le code du développeur peut inclure un script pour extraire le manifeste de l’application et déclencher la charge des initialiseurs JS.

Pour obtenir des exemples des initialiseurs JS, consultez les ressources suivantes :

• Indicateur de chargement Blazor Web App (rendu Global Interactive WebAssembly sans exemple de pré-rendu)
• JavaScript ASP.NET CoreBlazor avec rendu côté serveur statique (SSR statique)
• Utiliser des composants Razor dans des applications JavaScript et des frameworks SPA (exemple de quoteContainer2)
• Gestion des événements ASP.NET CoreBlazor (exemple d’événement de collage de presse-papiers personnalisé)
• Activer la génération de code QR pour les applications d’authentificateur TOTP dans une Blazor Web App ASP.NET Core
• Application de test de base dans le dépôt GitHub ASP.NET Core (BasicTestApp.lib.module.js)

Remarque

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Vérifier que les bibliothèques sont chargées dans un ordre spécifique

Ajoutez des scripts personnalisés au <head> dans beforeStart et afterStarted dans l’ordre dans lequel ils doivent être chargés.

L’exemple suivant charge script1.js avant script2.js et script3.js avant script4.js :

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

Importer des modules supplémentaires

Utilisez des instructions import de niveau supérieur dans le fichier d’initialiseurs JS pour importer des modules supplémentaires.

additionalModule.js :

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

Dans le fichier d’initialiseurs JS (.lib.module.js) :

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

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

  logMessage();
}

Importer une carte

Les mappages d’importation sont pris en charge par ASP.NET Core et Blazor.

Initialiser Blazor lorsque le document est prêt

L’exemple suivant démarre Blazor lorsque le document est prêt :

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

Dans l’exemple précédent, l’espace réservé {BLAZOR SCRIPT} est le chemin d’accès de script Blazor et le nom de fichier. Pour connaître l’emplacement du script, consultez ASP.NET Core Blazor structure du projet.

Chaîne vers le Promise qui résulte d’un démarrage manuel

Pour effectuer des tâches supplémentaires, comme l’initialisation de l’interopérabilité JS, utilisez then pour chaîner le Promise résultant d’un démarrage d’application Blazor manuel :

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

Dans l’exemple précédent, l’espace réservé {BLAZOR SCRIPT} est le chemin d’accès de script Blazor et le nom de fichier. Pour connaître l’emplacement du script, consultez ASP.NET Core Blazor structure du projet.

Remarque

Pour qu’une bibliothèque exécute automatiquement des tâches supplémentaires après le démarrage de Blazor, utilisez un initialiseur JavaScript. L’utilisation d’un initialiseur JS ne nécessite pas que le consommateur de la bibliothèque enchaîne des appels JS au démarrage manuel de Blazor.

Charger des ressources de démarrage côté client

Lorsqu’une application se charge dans le navigateur, l’application télécharge les ressources de démarrage à partir du serveur :

• Code JavaScript pour démarrer l’application
• Environnement d'exécution et assemblies .NET
• Données spécifiques aux paramètres régionaux

Personnalisez la façon dont ces ressources de démarrage sont chargées à l’aide de l’API loadBootResource. La fonction loadBootResource remplace le mécanisme de chargement des ressources de démarrage intégré. Utilisez loadBootResource pour les scénarios suivants :

• Charger des ressources statiques, comme des données de fuseau horaire ou dotnet.wasm, à partir d’un CDN.
• Charger des assemblies compressées à l’aide d’une requête HTTP et les décompresser sur le client pour les hôtes qui ne prennent pas en charge la récupération des contenus compressés à partir du serveur.
• Donner un alias aux ressources en redirigeant chaque requête fetch vers un nouveau nom.

Remarque

Les sources externes doivent retourner les en-têtes CORS (partage de ressources cross-origin) requis pour que les navigateurs autorisent le chargement des ressources entre les origines. Les réseaux de diffusion de contenu (CDN) fournissent généralement les en-têtes requis.

Les paramètres loadBootResource apparaissent dans le tableau suivant.

Paramètre	Descriptif
type	Type de la ressource. Les types possibles sont notamment assembly, pdb, dotnetjs, dotnetwasm et timezonedata. Vous devez spécifier des types seulement pour les comportements personnalisés. Les types non spécifiés comme loadBootResource sont chargés par le framework en fonction de leurs comportements de chargement par défaut. La ressource de démarrage dotnetjs (dotnet.*.js) doit retourner null pour le comportement de chargement par défaut ou un URI pour la source de la ressource de démarrage dotnetjs.
name	Nom de la ressource.
defaultUri	URI relatif ou absolu de la ressource.
integrity	Chaîne d’intégrité représentant le contenu attendu dans la réponse.

La fonction loadBootResource peut retourner une chaîne d’URI pour remplacer le processus de chargement. Dans l’exemple suivant, les fichiers suivants de bin/Release/{TARGET FRAMEWORK}/wwwroot/_framework sont servis à partir d’un CDN sur https://cdn.example.com/blazorwebassembly/{VERSION}/ :

• dotnet.*.js
• dotnet.wasm
• Données de fuseau horaire

L’espace réservé {TARGET FRAMEWORK} correspond au moniker de framework cible (par exemple net7.0). L’espace réservé {VERSION} correspond à la version de framework partagé (par exemple 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 autonome :

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

Dans l’exemple précédent, l’espace réservé {BLAZOR SCRIPT} est le chemin d’accès de script Blazor et le nom de fichier. Pour connaître l’emplacement du script, consultez ASP.NET Core Blazor structure du projet.

Pour personnaliser plus d’éléments que les URL des ressources de démarrage, la fonction loadBootResource peut appeler fetch directement et retourner le résultat. L’exemple suivant ajoute un en-tête HTTP personnalisé aux requêtes sortantes. Pour conserver le comportement de vérification de l’intégrité par défaut, passez le paramètre integrity.

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 autonome :

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

Dans l’exemple précédent, l’espace réservé {BLAZOR SCRIPT} est le chemin d’accès de script Blazor et le nom de fichier. Pour connaître l’emplacement du script, consultez ASP.NET Core Blazor structure du projet.

Lorsque la fonction loadBootResource retourne null, Blazor utilise le comportement de chargement par défaut pour la ressource. Par exemple, le code précédent retourne null pour la ressource de démarrage dotnetjs (dotnet.*.js), car la ressource de démarrage dotnetjs doit retourner null pour le comportement de chargement par défaut ou un URI pour la source de la ressource de démarrage dotnetjs .

La fonction loadBootResource peut également retourner une promesse Response. Pour obtenir un exemple, consultez Héberger et déployer ASP.NET Core Blazor WebAssembly.

Pour plus d’informations, consultez les échecs de mise en cache et de vérification de l’intégrité des bundles .NET dans ASP.NET CoreBlazor WebAssembly.

Contrôler les en-têtes dans le code C#

Contrôlez les en-têtes au démarrage dans le code C# à l’aide des approches suivantes.

Dans les exemples suivants, une stratégie de sécurité du contenu (CSP) est appliquée à l’application via un en-tête CSP. L’espace réservé {POLICY STRING} est la chaîne de stratégie CSP. Pour plus d’informations sur les CSP, consultez Appliquer une stratégie de sécurité de contenu pour ASP.NET Core Blazor.

Remarque

Les en-têtes ne peuvent pas être définis après le démarrage de la réponse. Les approches de cette section définissent uniquement les en-têtes avant le démarrage de la réponse. Les approches décrites ici sont donc sécurisées. Pour plus d'informations, consultez IHttpContextAccessor/HttpContext dans les applications ASP.NET Core Blazor.

Scénarios côté serveur et pré-rendus côté client

Utilisez l’intergiciel ASP.NET Core pour contrôler la collection d’en-têtes.

Dans le fichier Program :

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

L’exemple précédent utilise l’intergiciel inline, mais vous pouvez également créer une classe d’intergiciels personnalisée et appeler l’intergiciel avec une méthode d’extension dans le fichier Program. Pour plus d’informations, consultez Écrire un intergiciel ASP.NET Core personnalisé.

Indicateurs de chargement côté client

Un indicateur de chargement indique que l’application se charge normalement et que l’utilisateur doit attendre que le chargement soit terminé.

Blazor Web App indicateur de chargement

L’indicateur de chargement utilisé dans les Blazor WebAssembly applications n’est pas présent dans une application créée à partir du modèle de Blazor Web App projet. En règle générale, un indicateur de chargement n’est pas souhaitable pour les composants WebAssembly interactifs, car les composants côté client sont pré-rendus sur le serveur par Blazor Web App pour des temps de chargement initial rapides. Pour les situations en mode de rendu mixte, le code du framework ou du développeur doit également faire attention à éviter les problèmes suivants :

• Afficher plusieurs indicateurs de chargement sur la même page rendue.
• Éliminer par inadvertance le contenu prérendu pendant le chargement du runtime .NET WebAssembly.

Une prochaine version de .NET peut fournir un indicateur de chargement basé sur le framework. En attendant, vous pouvez ajouter un indicateur de chargement personnalisé à un Blazor Web App.

Rendu interactif WebAssembly par composant avec pré-rendu

Ce scénario s’applique au rendu interactif par composant WebAssembly (@rendermode InteractiveWebAssembly appliqué à des composants individuels).

Créez un composant ContentLoading dans le dossier Layout de l’application .Client qui appelle OperatingSystem.IsBrowser:

• Lorsque false, affichez un indicateur de chargement.
• Si la valeur est true, affichez le rendu du contenu du composant demandé.

Pour charger les styles CSS pour l’indicateur, ajoutez les styles au contenu <head> avec le composant HeadContent. Pour plus d’informations, consultez Contrôle du contenu des en-têtes dans les applications ASP.NET Core 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; }
}

Si vous n’avez pas encore de Layout dossier dans le .Client projet, ajoutez l’espace de noms du Layout dossier au _Imports.razor fichier. Dans l’exemple suivant, l’espace de noms du projet est BlazorSample.Client:

@using BlazorSample.Client.Layout

Dans un composant qui adopte un rendu WebAssembly interactif, enveloppez le balisage Razor du composant avec le composant ContentLoading. L’exemple suivant illustre l’approche avec le composant Counter d’une application créée à partir du modèle de projet Blazor Web App.

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++;
    }
}

Rendu global interactif WebAssembly avec pré-rendu

Ce scénario s’applique au rendu global interactif WebAssembly avec le prérendu (@rendermode="InteractiveWebAssembly" sur les composants HeadOutlet et Routes dans le composant App).

Créez un composant ContentLoading dans le dossier Layout de l’application .Client qui appelle RendererInfo.IsInteractive:

• Lorsque false, affichez un indicateur de chargement.
• Si la valeur est true, affichez le rendu du contenu du composant demandé.

Pour charger les styles CSS pour l’indicateur, ajoutez les styles au contenu <head> avec le composant HeadContent. Pour plus d’informations, consultez Contrôle du contenu des en-têtes dans les applications ASP.NET Core 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; }
}

Si vous n’avez pas encore de Layout dossier dans le .Client projet, ajoutez l’espace de noms du Layout dossier au _Imports.razor fichier. Dans l’exemple suivant, l’espace de noms du projet est BlazorSample.Client:

@using BlazorSample.Client.Layout

Dans le composant MainLayout (Layout/MainLayout.razor) du projet .Client, encapsulez la propriété Body (@Body) avec le composant ContentLoading.

Dans Layout/MainLayout.razor :

+ <ContentLoading>
    @Body
+ </ContentLoading>

Rendu global interactif WebAssembly sans pré-rendu

Ce scénario s'applique au rendu global de WebAssembly interactif sans pré-rendu (@rendermode="new InteractiveWebAssemblyRenderMode(prerender: false)" sur les composants HeadOutlet et Routes dans le composant App).

Ajoutez un initialiseur JavaScript à l’application. Dans l’exemple de nom de fichier de module JavaScript suivant, l’espace {ASSEMBLY NAME} réservé est le nom d’assembly du projet de serveur (par exemple, BlazorSample). Le wwwroot dossier où le module est placé est le wwwroot dossier du projet côté serveur, et non le .Client projet.

L’exemple suivant utilise un progress indicateur qui n’indique pas la progression réelle de la remise des ressources de démarrage côté client au client, mais sert d’approche générale pour un développement plus approfondi si vous souhaitez que l’indicateur de progression affiche la progression réelle du chargement des ressources de démarrage de l’application.

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();
}

En raison d’un bogue de framework dans .NET 8 et 9 (dotnet/aspnetcore #54049),le Blazor script doit être démarré manuellement. Si l'application serveur ne démarre pas encore Blazor manuellement avec une configuration WebAssembly (webAssembly: {...}), mettez à jour le composant App dans le projet serveur en suivant ces étapes.

Dans Components/App.razor, supprimez la balise existante Blazor<script> :

- <script src="_framework/blazor.web.js"></script>

Remplacez la balise <script> par le balisage suivant qui commence Blazor manuellement par une configuration WebAssembly (webAssembly: {...}) :

<script src="_framework/blazor.web.js" autostart="false"></script>
<script>
    Blazor.start({
        webAssembly: {}
    });
</script>

Si vous constatez un court délai entre la suppression de l’indicateur de chargement et le premier rendu de page, vous pouvez garantir la suppression de l’indicateur après le rendu en appelant la suppression d’indicateur dans la OnAfterRenderAsync méthode de cycle de vie des composants MainLayout ou Routes. Pour plus d’informations et un exemple de code, consultez Documenter une approche pour un indicateur de chargement qui fonctionne avec global Interactive WebAssembly sans pré-rendu (dotnet/AspNetCore.Docs #35111).

Progression du chargement des applications Blazor WebAssembly

Le modèle de projet contient des graphiques vectoriels évolutifs (SVG) et des indicateurs de texte qui signalent la progression du chargement de l’application.

Les indicateurs de progression sont implémentés avec HTML et CSS à l’aide de deux propriétés CSS personnalisées (variables) fournies par Blazor :

• --blazor-load-percentage : pourcentage des fichiers d’application chargé.
• --blazor-load-percentage-text : pourcentage des fichiers d’application chargé, arrondi au nombre entier le plus proche.

À l’aide des variables CSS précédentes, vous pouvez créer des indicateurs de progression personnalisés qui correspondent au style de votre application.

Dans l’exemple suivant :

• resourcesLoaded est un nombre instantané des ressources chargées au démarrage de l’application.
• totalResources est le nombre total de ressources à charger.

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’indicateur de progression arrondi par défaut est implémenté en HTML dans le fichier 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>

Pour passer en revue le balisage et le style du modèle de projet pour les indicateurs de progression par défaut, consultez la source de référence ASP.NET Core :

• wwwroot/index.html
• app.css

Remarque

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Au lieu d’utiliser l’indicateur de progression arrondi par défaut, l’exemple suivant montre comment implémenter un indicateur de progression linéaire.

Ajoutez les styles suivants à 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;
}

Une variable CSS (var(...)) est utilisée pour passer la valeur de --blazor-load-percentage à la propriété scale d’un pseudo-élément bleu qui indique la progression du chargement des fichiers de l’application. À mesure que l’application se charge, --blazor-load-percentage est mis à jour automatiquement, ce qui modifie dynamiquement la représentation visuelle de l’indicateur de progression.

Dans wwwroot/index.html, supprimez l’indicateur d’arrondi SVG par défaut dans <div id="app">...</div> et remplacez-le par le balisage suivant :

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

Configurer le runtime .NET WebAssembly

Dans les scénarios de programmation avancés, la fonction configureRuntime avec le générateur d’hôtes du runtime dotnet est utilisée pour configurer le runtime .NET WebAssembly. Par exemple, dotnet.withEnvironmentVariable définit une variable d’environnement qui :

• Configure le runtime .NET WebAssembly.
• Modifie le comportement d’une bibliothèque C.

Remarque

Une demande de documentation est en attente dans le référentiel GitHub dotnet/runtime pour plus d’informations sur les variables d’environnement qui configurent le runtime .NET WebAssembly ou qui affectent le comportement des bibliothèques C. Bien que la demande de documentation soit en attente, des informations supplémentaires et des liens croisés vers des ressources supplémentaires sont disponibles dans la demande, question/demande de documentation sur le runtime .NET WASM env vars (dotnet/runtime #98225).

La fonction configureRuntime peut également être utilisée pour activer l’intégration à un profil de navigateur.

Pour les variables de remplacement dans les exemples suivants qui définissent une variable d’environnement :

• L’espace réservé {BLAZOR SCRIPT} correspond au chemin et au nom de fichier de script Blazor. Pour connaître l’emplacement du script, consultez ASP.NET Core Blazor structure du projet.
• L’espace réservé {NAME} est le nom de la variable d’environnement.
• L’espace réservé {VALUE} est la valeur de la variable d’environnement.

Blazor Web App :

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

Blazor WebAssembly autonome :

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

Remarque

L’instance du runtime .NET est accessible à l’aide de l’API Runtime .NET WebAssembly (Blazor.runtime). Par exemple, la configuration de build de l’application peut être obtenue à l’aide de Blazor.runtime.runtimeBuildInfo.buildConfiguration.

Pour plus d’informations sur la configuration du runtime .NET WebAssembly, consultez le fichier de définition TypeScript du runtime (dotnet.d.ts) dans le dotnet/runtime référentiel GitHub.

Remarque

Les liens de documentation vers la source de référence .NET chargent généralement la branche par défaut du référentiel, qui représente le développement actuel pour la prochaine version de .NET. Pour sélectionner une balise pour une version spécifique, utilisez la liste déroulante Échanger les branches ou les balises. Pour plus d’informations, consultez Comment sélectionner une balise de version du code source ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Désactiver la navigation améliorée et la gestion des formulaires

Cette section s’applique aux Blazor Web Apps.

Pour désactiver la navigation et la gestion des formulaires améliorées, définissez disableDomPreservation sur true pour Blazor.start :

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

Dans l’exemple précédent, l’espace réservé {BLAZOR SCRIPT} est le chemin d’accès de script Blazor et le nom de fichier. Pour connaître l’emplacement du script, consultez ASP.NET Core Blazor structure du projet.

Ressources supplémentaires

• Environnements : définir l’environnement de l’application
• SignalR (inclut des sections sur la configuration de démarrage de SignalR)
• Globalisation et localisation : définir statiquement la culture avec Blazor.start() (côté client uniquement)
• Compression Blazor WebAssembly