Fichiers statiques ASP.NET Core Blazor

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

Pour obtenir des informations générales sur le service de fichiers statiques avec les conventions de point de terminaison de routage Map Static Assets, consultez Map static files in ASP.NET Core avant de lire cet article.

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

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 (Interface de Programmation d'Applications)	Version .NET	Descriptif
Mappage des conventions de points de terminaison de routage des actifs 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 de Map Static Assets, mais utile pour certaines tâches que Map Static Assets n'est pas capable de gérer.

Les ressources statiques mappées peuvent être remplacées UseStaticFiles dans la plupart des situations. Cependant, Map Static Assets est optimisé pour servir les ressources à partir d'emplacements connus dans l'application au moment de la création 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 également l'appel à UseBlazorFrameworkFiles dans les applications qui fournissent des fichiers Blazor WebAssembly du framework, et l'appel explicite à UseBlazorFrameworkFiles dans un élément Blazor Web App n'est pas nécessaire, car l'API est automatiquement appelée lorsque l'on appelle AddInteractiveWebAssemblyComponents.

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.

L’intergiciel de fichiers statiques (UseStaticFiles) est utile dans les situations suivantes que la cartographie des ressources statiques (MapStaticAssets) ne peut pas gérer :

• Service de fichiers à partir du disque qui ne font pas partie du processus de génération ou de publication, par exemple, des fichiers ajoutés au dossier d’application pendant ou après le déploiement.
• 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 les conventions de point de terminaison de mappage d'actifs statiques

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

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

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

ImportMap composant

Cette section s’applique aux Blazor Web App qui appellent MapRazorComponents.

Le ImportMap composant (ImportMap) représente un élément de mappage 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 le contenu du composant racine, généralement le composant <head> (App).

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

Remarque

ImportMapDefinition Les instances sont coûteuses à créer. Nous vous recommandons donc de les mettre en cache lors de la création d’une instance supplémentaire.

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'importation étendue :

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

Importer le mappage 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’un ResourceAssetCollection qui associe 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"
  }
}

Importation de mappage des violations de la politique de sécurité du contenu (CSP)

Cette section s’applique aux Blazor Web App qui appellent MapRazorComponents.

Le ImportMap composant est rendu sous la forme d’une balise <script> en ligne, qui enfreint une stratégie de sécurité de contenu (CSP) stricte qui définit la directive default-src ou script-src.

Pour des exemples sur la façon de traiter la violation de la stratégie avec l'intégrité des sous-ressources (SRI) ou un nombre aléatoire cryptographique, voir Résoudre les violations de la CSP avec l'intégrité des sous-ressources (SRI) ou un nombre aléatoire.

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" />
Autonome Blazor WebAssembly	{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" />
Autonome Blazor WebAssembly	{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" />
Hébergé Blazor WebAssembly‡	{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.

Avertissement

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 ressources Blazor WebAssembly

Cette section s’applique aux Blazor Web Apps.

Utilisez l'option de point de terminaison WebAssemblyComponentsEndpointOptions.PathPrefix pour définir la chaîne de chemin indiquant 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, le caractère générique {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 de base d'accès aux ressources statiques web

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 Blazor framework (_framework folder assets), au chemin 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).

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 autonome Blazor WebAssembly 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).

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 conseils de cette section ne s'appliquent qu'aux Blazor Web Apps

Pour servir des fichiers depuis 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. Réaffectez le fournisseur du fichier composite 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 alternatif de l'image.

Exécutez l'application.

Ressources supplémentaires

• chemin de base de l’application ASP.NET Core Blazor
• Éviter la capture de fichiers dans un paramètre de route