Fichiers statiques ASP.NET Core Blazor

Cet article décrit la configuration d’application Blazor pour servir des fichiers statiques.

Remise de ressources statiques dans les applications côté Blazor serveur

Le service des ressources statiques est géré par des conventions de point de terminaison de routage ou un intergiciel décrit dans le tableau suivant.

Fonctionnalité	API	Version .NET	Description
Mapper les conventions de point de terminaison de routage des ressources statiques	MapStaticAssets	.NET 9 ou version ultérieure	Permet d’optimiser la remise de ressources statiques aux clients.
Intergiciel des fichiers statiques	UseStaticFiles	Toutes les versions .NET	Sert des ressources statiques aux clients sans les optimisations des ressources statiques mappées, mais utiles pour certaines tâches que mapper les ressources statiques ne sont pas capables de gérer.

Configurez mapper les ressources statiques en appelant MapStaticAssets le pipeline de traitement des demandes de l’application, qui effectue les opérations suivantes :

• Définition des en-têtes ETag et Last-Modified (Dernière modification).
• Définition des en-têtes de mise en cache.
• Utilisation d’un Intergiciel de mise en cache.
• Lorsque cela est possible, distribue des ressources statiques compressées.
• Fonctionne avec un Réseau de distribution de contenu (CDN) (par exemple, Azure CDN) pour distribuer les ressources statiques de l’application de manière plus proche de l’utilisateur.
• Prise d’empreinte numérique des ressources pour empêcher de réutiliser les anciennes versions de fichiers.

Mapper les ressources statiques fonctionne en combinant des processus de génération et de publication pour collecter des informations sur les ressources statiques dans l’application. Ces informations sont utilisées par la bibliothèque runtime pour distribuer efficacement ces fichiers à des navigateurs.

Les ressources statiques mappées peuvent être remplacées UseStaticFiles dans la plupart des situations. Toutefois, mapper les ressources statiques est optimisée pour servir les ressources à partir d’emplacements connus dans l’application au moment de la génération et de la publication. Si l’application sert des ressources à partir d’autres emplacements, tels que des ressources sur disque ou incorporées, UseStaticFiles doit être utilisé.

Mapper les ressources statiques (MapStaticAssets) remplace l’appel UseBlazorFrameworkFiles dans les applications qui servent Blazor WebAssembly des fichiers framework, et l’appel UseBlazorFrameworkFiles explicite dans un Blazor Web App élément n’est pas nécessaire, car l’API est automatiquement appelée lors de l’appel AddInteractiveWebAssemblyComponents.

Les ressources statiques mappées offrent les avantages suivants qui ne sont pas disponibles lors de l’appel UseStaticFiles:

• Compression au moment de la génération pour toutes les ressources de l’application, y compris JavaScript (JS) et les feuilles de style, mais pas les ressources d’image et de police déjà compressées. La compression Gzip (Content-Encoding: gz) est utilisée pendant le développement. La compression Gzip avec Brotli (Content-Encoding: br) est utilisée pendant la publication.
• Prise d’empreinte numérique de toutes les ressources au moment de la génération avec une chaîne encodée en Base64 du hachage SHA-256 du contenu de chaque fichier. Cela empêche de réutiliser une ancienne version d’un fichier, même si l’ancien fichier est mis en cache. Les ressources qui ont fait l’objet d’une empreinte numérique sont mises en cache à l’aide de la directive immutable, ce qui permet au navigateur de ne jamais redemander la ressource tant qu’elle n’a pas changé. Pour les navigateurs qui ne prennent pas en charge la directive immutable , une directive max-age est ajoutée.
  • Même si une ressource n’a pas fait l’objet d’une empreinte numérique, les ETags de contenu sont générés pour chaque ressource statique à l’aide du hachage d’empreinte numérique du fichier en tant que valeur ETag. Cela garantit que le navigateur télécharge un fichier seulement si son contenu change (ou si le fichier est téléchargé pour la première fois).
  • En interne, Blazor mappe les ressources physiques à leurs empreintes numériques, ce qui permet à l’application de :
    • Rechercher les ressources Blazor automatiquement générées, telles que la feuille CSS délimitée aux composants Razor pour la fonctionnalité d’isolation CSS de Blazor et les ressources JS décrites par les cartes d’import JS.
    • Générer des balises de lien dans le contenu <head> de la page pour précharger les ressources.
• Pendant les tests de développement du Rechargement à chaud Visual Studio :
  • Les informations d’intégrité sont supprimées des ressources pour éviter les problèmes lorsqu’un fichier est modifié pendant l’exécution de l’application.
  • Les ressources statiques ne sont pas mises en cache pour s’assurer que le navigateur récupère toujours le contenu actuel.

Lorsque les modes de rendu interactifs WebAssembly ou Auto sont activés :

• Blazor crée un point de terminaison pour exposer la collection de ressources en tant que module JS.
• L’URL est émise dans le corps de la requête en tant qu’état de composant persistant lorsqu’un composant WebAssembly est rendu dans la page.
• Pendant le démarrage de WebAssembly, Blazor récupère l’URL, importe le module et appelle une fonction pour récupérer la collection de ressources et la reconstruire en mémoire. L’URL est spécifique au contenu et mise en cache pour toujours, donc ce coût de surcharge n’est payé qu’une seule fois par utilisateur tant que l’application n’est pas mise à jour.
• La collection de ressources est également exposée sur une URL lisible par les humains (_framework/resource-collection.js), de sorte que JS a accès à la collection de ressources pour une meilleure navigation ou pour implémenter des fonctionnalités d’autres frameworks et composants tiers.

Mapper les ressources statiques ne fournit pas de fonctionnalités pour la minification ou d’autres transformations de fichiers. La minification est généralement gérée par du code personnalisé ou des outils tiers.

L’intergiciel de fichiers statiques (UseStaticFiles) est utile dans les situations suivantes où mapper les ressources statiques (MapStaticAssets) ne peut pas gérer :

• Application d’un préfixe de chemin d’accès aux fichiers de ressources statiques Blazor WebAssembly, qui est abordée dans la section Préfixe pour des ressources Blazor WebAssembly.
• Configuration de mappages de fichiers d’extensions à des types de contenu spécifiques et définition des options de fichiers statiques, qui est abordée dans la section Mappages de fichiers et options de fichier statiques.

Pour plus d’informations, consultez Fichiers statiques dans ASP.NET Core.

Fournir des ressources avec des conventions de point de terminaison de routage des ressources statiques mappées

Cette section s’applique aux applications Blazor côté serveur.

Les ressources sont livrées via la ComponentBase.Assets propriété, ce qui résout l’URL d’empreinte digitale d’une ressource donnée. Dans l’exemple suivant, Bootstrap, la feuille de style de l’application Blazor modèle de projet (app.css) et la feuille de style d’isolation CSS (basée sur l’espace de noms d’une application) BlazorSamplesont liées dans un composant racine, généralement le App composant () :Components/App.razor

<link rel="stylesheet" href="@Assets["bootstrap/bootstrap.min.css"]" />
<link rel="stylesheet" href="@Assets["app.css"]" />
<link rel="stylesheet" href="@Assets["BlazorSample.styles.css"]" />

Cartes d’import

Cette section s’applique aux applications Blazor côté serveur.

Le composant Import Map (ImportMap) représente un élément de carte d’importation (<script type="importmap"></script>) qui définit le mappage d’importation pour les scripts de module. Le composant Import Map est placé dans <head> le contenu du composant racine, généralement le App composant (Components/App.razor).

<ImportMap />

Si une valeur personnalisée ImportMapDefinition n’est pas affectée à un composant Import Map, la carte d’importation est générée en fonction des ressources de l’application.

Les exemples suivants illustrent les définitions de carte d’import personnalisées et les cartes d’import qu’ils créent.

Carte d’import de base :

new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "jquery", "https://cdn.example.com/jquery.js" },
    },
    null,
    null);

Le code précédent génère la carte d’import suivante :

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  }
}

Carte d’import délimitée :

new ImportMapDefinition(
    null,
    new Dictionary<string, IReadOnlyDictionary<string, string>>
    {
        ["/scoped/"] = new Dictionary<string, string>
        {
            { "jquery", "https://cdn.example.com/jquery.js" },
        }
    },
    null);

Le code précédent génère la carte d’import suivante :

{
  "scopes": {
    "/scoped/": {
      "jquery": "https://cdn.example.com/jquery.js"
    }
  }
}

Carte d’import avec intégrité :

new ImportMapDefinition(
    new Dictionary<string, string>
    {
        { "jquery", "https://cdn.example.com/jquery.js" },
    },
    null,
    new Dictionary<string, string>
    {
        { "https://cdn.example.com/jquery.js", "sha384-abc123" },
    });

Le code précédent génère la carte d’import suivante :

{
  "imports": {
    "jquery": "https://cdn.example.com/jquery.js"
  },
  "integrity": {
    "https://cdn.example.com/jquery.js": "sha384-abc123"
  }
}

Combinez les définitions de carte d’import (ImportMapDefinition) avec ImportMapDefinition.Combine.

La carte d’import créée à partir d’une ResourceAssetCollection qui mappe les ressources statiques à leur URL unique correspondante :

ImportMapDefinition.FromResourceCollection(
    new ResourceAssetCollection(
    [
        new ResourceAsset(
            "jquery.fingerprint.js",
            [
                new ResourceAssetProperty("integrity", "sha384-abc123"),
                new ResourceAssetProperty("label", "jquery.js"),
            ])
    ]));

Le code précédent génère la carte d’import suivante :

{
  "imports": {
    "./jquery.js": "./jquery.fingerprint.js"
  },
  "integrity": {
    "jquery.fingerprint.js": "sha384-abc123"
  }
}

Dans les versions antérieures à .NET 8, les fichiers statiques de l’infrastructure Blazor, tels que le script Blazor, sont servis via le middleware de fichiers statiques. Dans .NET 8 ou version ultérieure, le middleware de fichiers statiques n’est plus utilisé, car les fichiers statiques de l’infrastructure Blazor sont mappés à l’aide du routage de point de terminaison.

Résumé des formats <link> href des fichiers statiques

Cette section s’applique à toutes les versions .NET et applications Blazor.

Les tableaux suivants récapitulent les formats de fichiers statiques <link> href par version .NET.

Pour connaître l’emplacement du contenu <head> où les liens de fichier statique sont placés, consultez Structure de projet Blazor ASP.NET Core. Les liens de ressources statiques peuvent également être fournis à l’aide des composants <HeadContent> dans les composants Razor individuels.

.NET 9 ou version ultérieure

Type d’application	Valeur href	Exemples
Blazor Web App	@Assets["{PATH}"]	<link rel="stylesheet" href="@Assets["app.css"]" /> <link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" />
Blazor Server†	@Assets["{PATH}"]	<link href="@Assets["css/site.css"]" rel="stylesheet" /> <link href="@Assets["_content/ComponentLib/styles.css"]" rel="stylesheet" />
Blazor WebAssembly autonome	{PATH}	<link rel="stylesheet" href="css/app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 8.x

Type d’application	Valeur href	Exemples
Blazor Web App	{PATH}	<link rel="stylesheet" href="app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Blazor Server†	{PATH}	<link href="css/site.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Blazor WebAssembly autonome	{PATH}	<link rel="stylesheet" href="css/app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 7.x ou antérieur

Type d’application	Valeur href	Exemples
Blazor Server†	{PATH}	<link href="css/site.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Blazor WebAssembly hébergé‡	{PATH}	<link href="css/app.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Blazor WebAssembly	{PATH}	<link href="css/app.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />

†Blazor Server est pris en charge dans .NET 8 ou ultérieur, mais n’est plus un modèle de projet après la version .NET 7.
‡Nous vous recommandons de mettre à jour les applications Blazor WebAssembly hébergées vers des applications Blazor Web App lorsque vous adoptez .NET 8 ou ultérieur.

Mode projet d’une ressource web statique

Cette section s’applique au projet .Client d’une application Blazor Web App.

Le paramètre requis <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> dans le projet .Client d’une application Blazor Web App rétablit les comportements de ressources statiques Blazor WebAssembly par défaut afin que le projet se comporte comme partie intégrante du projet hébergé. Le Kit de développement logiciel (SDK) Blazor WebAssembly (Microsoft.NET.Sdk.BlazorWebAssembly) configure les ressources web statiques d’une manière spécifique pour fonctionner en mode « autonome » avec un serveur qui consomme simplement les sorties de la bibliothèque. Cette action n’est pas appropriée pour une application Blazor Web App, où la partie WebAssembly de l’application constitue une partie logique de l’hôte et doit se comporter davantage comme une bibliothèque. Par exemple, le projet n’expose pas le bundle de styles (par exemple BlazorSample.Client.styles.css) et fournit uniquement l’hôte à la place avec le bundle de projet afin que l’hôte puisse l’inclure dans son propre bundle de styles.

La modification de la valeur (Default) de <StaticWebAssetProjectMode> ou la suppression de la propriété du projet .Client n’est pas prise en charge.

Fichiers statiques dans des environnements non Development

Cette section s’applique aux fichiers statiques côté serveur.

Lors de l’exécution locale d’une application, les ressources web statiques sont uniquement activées dans l’environnement Development. Pour activer les fichiers statiques pour des environnements autres que Development pendant le développement et le test locaux (par exemple, Staging), appelez UseStaticWebAssets sur WebApplicationBuilder dans le fichier Program.

Warning

Appelez UseStaticWebAssets pour l’environnement exact pour empêcher l’activation de la fonctionnalité en production, car elle délivre des fichiers provenant d’emplacements distincts sur le disque autres que le projet si elle est appelée dans un environnement de production. L’exemple de cette section vérifie l’environnement Staging en appelant IsStaging.

if (builder.Environment.IsStaging())
{
    builder.WebHost.UseStaticWebAssets();
}

Préfixe pour les ressources Blazor WebAssembly

Cette section s’applique aux Blazor Web App.

Utilisez l’option WebAssemblyComponentsEndpointOptions.PathPrefix le point de terminaison pour définir la chaîne de chemin qui indique le préfixe des ressources Blazor WebAssembly. Le chemin d’accès doit correspondre à un projet d’application référencé Blazor WebAssembly.

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "{PATH PREFIX}");

Dans l’exemple précédent, l’espace réservé {PATH PREFIX} est le préfixe du chemin d’accès et doit commencer par une barre oblique (/).

Dans l’exemple suivant, le préfixe de chemin d’accès est défini sur /path-prefix :

endpoints.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode(options => 
        options.PathPrefix = "/path-prefix");

Chemin d’accès de base des ressources web statiques

Cette section s’applique aux applications Blazor WebAssembly autonomes.

La publication de l’application place les ressources statiques de l’application, y compris les fichiers de l’infrastructure Blazor (ressources du dossier _framework), au niveau du chemin d’accès racine (/) dans la sortie publiée. La propriété <StaticWebAssetBasePath> spécifiée dans le Fichier projet (.csproj) définit le chemin d’accès de base à un chemin d’accès non racine :

<PropertyGroup>
  <StaticWebAssetBasePath>{PATH}</StaticWebAssetBasePath>
</PropertyGroup>

Dans l’exemple précédent, l’espace réservé {PATH} est le chemin d’accès.

Sans définir la propriété <StaticWebAssetBasePath>, une application autonome est publiée à /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/.

Dans l’exemple précédent, l’espace réservé {TFM} est le Moniker du framework cible (TFM) (par exemple, net6.0).

Si la propriété <StaticWebAssetBasePath> dans une application Blazor WebAssembly autonome définit le chemin d’accès à la ressource statique publiée sur app1, le chemin racine de l’application dans la sortie publiée est /app1.

Dans le fichier projet de l’application Blazor WebAssembly autonome (.csproj) :

<PropertyGroup>
  <StaticWebAssetBasePath>app1</StaticWebAssetBasePath>
</PropertyGroup>

Dans la sortie publiée, le chemin d’accès à l’application Blazor WebAssembly autonome est /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/.

Dans l’exemple précédent, l’espace réservé {TFM} est le Moniker du framework cible (TFM) (par exemple, net6.0).

Mappages de fichiers et options de fichier statiques

Cette section s’applique aux fichiers statiques côté serveur.

Pour créer des mappages de fichiers supplémentaires avec un FileExtensionContentTypeProvider ou configurer d’autres StaticFileOptions, utilisez l’une des approches suivantes. Dans les exemples suivants, l’espace réservé {EXTENSION} est l’extension de fichier et l’espace réservé {CONTENT TYPE} est le type de contenu. L’espace de noms de l’API suivante est Microsoft.AspNetCore.StaticFiles.

• Configurez les options via l’injection de dépendances (DI) dans le fichier Program à l’aide de StaticFileOptions :

  var provider = new FileExtensionContentTypeProvider();
  provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";
  
  builder.Services.Configure<StaticFileOptions>(options =>
  {
      options.ContentTypeProvider = provider;
  });
  
  app.UseStaticFiles();
  

• Passez StaticFileOptions directement à UseStaticFiles dans le fichier Program :

  var provider = new FileExtensionContentTypeProvider();
  provider.Mappings["{EXTENSION}"] = "{CONTENT TYPE}";
  
  app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
  

Délivrer des fichiers à partir de plusieurs emplacements

Les instructions de cette section s’appliquent uniquement aux Blazor Web App.

Pour servir des fichiers de plusieurs emplacements avec un CompositeFileProvider :

• Ajoutez l’espace de noms pour Microsoft.Extensions.FileProviders en haut du fichier Program du projet serveur.
• Dans le fichier Program du projet serveur avant l’appel à UseStaticFiles :
  • Créez un PhysicalFileProvider avec le chemin d’accès aux ressources statiques.
  • Créez un CompositeFileProvider à partir du WebRootFileProvider et du PhysicalFileProvider. Affectez le fournisseur de fichiers composites au WebRootFileProvider de l’application.

Exemple :

Créez un dossier dans le projet serveur nommé AdditionalStaticAssets. Placez une image dans le dossier.

Ajoutez l’instruction using suivante en haut du fichier Program du projet serveur :

using Microsoft.Extensions.FileProviders;

Dans le fichier Program du projet serveur avant l’appel à UseStaticFiles, ajoutez le code suivant :

var secondaryProvider = new PhysicalFileProvider(
    Path.Combine(builder.Environment.ContentRootPath, "AdditionalStaticAssets"));
app.Environment.WebRootFileProvider = new CompositeFileProvider(
    app.Environment.WebRootFileProvider, secondaryProvider);

Dans le balisage du composant Home (Home.razor) de l’application, référencez l’image avec une balise <img> :

<img src="{IMAGE FILE NAME}" alt="{ALT TEXT}" />

Dans l'exemple précédent :

• L’espace réservé {IMAGE FILE NAME} est le nom du fichier image. Il n’est pas nécessaire de fournir un segment de chemin si le fichier image se trouve à la racine du dossier AdditionalStaticAssets.
• L’espace réservé {ALT TEXT} est le texte de remplacement de l’image.

Exécutez l'application.

Ressources supplémentaires

• Chemin de base de l’application
• Éviter la capture de fichiers dans un paramètre de route