Démarrage ASP.NET Core Blazor

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

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

• server pour une application Blazor Server
• webassembly pour une application Blazor WebAssembly

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 :

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.

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

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)

• 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é)
• Disposition du déploiement pour les applications hébergées ASP.NET Core Blazor WebAssembly
• Application de test de base dans le dépôt GitHub ASP.NET Core (BasicTestApp.lib.module.js)

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.

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 :

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 :

Dans le fichier Program :

Dans Startup.Configure de Startup.cs :

Développement côté client sans pré-rendu

Passez StaticFileOptions à MapFallbackToFile qui spécifie les en-têtes de réponse à l’étape de OnPrepareResponse.

Dans le fichier Program côté serveur :

Dans Startup.Configure de Startup.cs :

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

...

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

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

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.

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>

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.