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 les Blazor Web App :

• beforeWebStart(options) : appelée avant le démarrage de Blazor Web App. Par exemple, beforeWebStart il est utilisé pour personnaliser le processus de chargement, le niveau de journalisation et d’autres options. Reçoit les Blazor options Web (options).
• afterWebStarted(blazor) : appelé après toutes les promesses beforeWebStart résolues. Par exemple, afterWebStarted vous pouvez l’utiliser pour inscrire Blazor des écouteurs d’événements 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 (options) et toutes les extensions (extensions) ajoutéesSignalRlors de la publication.
• afterServerStarted(blazor) : appelé après le démarrage du premier runtime interactive server.
• 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’initialiseur héritée est imprévisible.

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

Pour Blazor Server, Blazor WebAssemblyet Blazor Hybrid les applications :

• 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 en afterStarted 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 un Promise et la promesse est attendue avant que le start-up 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 les 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.

Pour Blazor Server, Blazor WebAssemblyet Blazor Hybrid les applications :

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 :

• 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 Core Blazor (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
• Runtime et assemblys .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 assemblys compressés à l’aide d’une requête HTTP et les décompresser sur le client pour les hôtes qui ne prennent pas en charge l’extraction du contenu compressé à 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	Description
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 runtime ASP.NET Core Blazor WebAssembly .NET et la mise en cache du bundle d’applications.

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.

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

Pour plus d’informations sur les CSP, consultez Appliquer une stratégie de sécurité de contenu pour ASP.NET Core Blazor.

Indicateurs de progression de chargement côté client

Un indicateur de progression du chargement montre la progression du chargement de l’application aux utilisateurs en indiquant que l’application se charge normalement et que l’utilisateur doit attendre la fin du chargement.

Progression du chargement de Blazor Web App

L’indicateur de progression de chargement utilisé dans les applications Blazor WebAssembly n’est pas présent dans les applications créées à partir du modèle de projet Blazor Web App. L’indicateur de progression de chargement n’est généralement pas souhaitable pour les composants WebAssembly interactifs, car les Blazor Web App offrent un prérendu des composants côté client sur le serveur, les temps de chargement initial étant courts. 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.
• Ignorer le contenu prérendu par inadvertance pendant le chargement du runtime .NET WebAssembly.

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

Créez un composant LoadingProgress dans l’application .Client qui appelle OperatingSystem.IsBrowser :

• Si la valeur est false, affichez un indicateur de progression de chargement pendant le téléchargement du bundle Blazor et avant l’activation du runtime Blazor sur le client.
• Si la valeur est true, affichez le rendu du contenu du composant demandé.

La démonstration suivante utilise l’indicateur de progression de chargement que vous trouvez dans les applications créées à partir du modèle Blazor WebAssembly, notamment une modification des styles que le modèle fournit. Les styles sont chargés dans le contenu <head> de l’application par le composant HeadContent. Pour plus d’informations, consultez Contrôle du contenu des en-têtes dans les applications ASP.NET Core Blazor.

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

Dans un composant qui adopte un rendu WebAssembly interactif, enveloppez le balisage Razor du composant avec le composant LoadingProgress. 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>

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

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 espaces réservés dans les exemples suivants qui définissent une variable d’environnement :

• L’espace réservé {BLAZOR SCRIPT} correspond au chemin d’accès au script et au nom de fichier 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 App.

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)
• Héberger et déployer : Blazor WebAssembly : Compression