Partager via

Fichiers statiques ASP.NET Core Blazor

  • Article

Remarque

Ceci n’est pas la dernière version de cet article. Pour la version actuelle, consultez la version .NET 8 de cet article.

Avertissement

Cette version d’ASP.NET Core n’est plus prise en charge. Pour plus d’informations, consultez la Stratégie de prise en charge de .NET et .NET Core. Pour la version actuelle, consultez la version .NET 8 de cet article.

Important

Ces informations portent sur la préversion du produit, qui est susceptible d’être en grande partie modifié avant sa commercialisation. Microsoft n’offre aucune garantie, expresse ou implicite, concernant les informations fournies ici.

Pour la version actuelle, consultez la version .NET 8 de cet article.

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

Intergiciel de ressources statiques

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

La distribution de ressources statiques est gérée par l’un des deux intergiciels décrits dans la table suivante.

Middleware API Version .NET Description
Mappage de ressources statiques MapStaticAssets .NET 9 ou version ultérieure Permet d’optimiser la remise de ressources statiques aux clients.
Fichiers statiques UseStaticFiles Toutes les versions .NET Permet de distribuer des ressources statiques aux clients sans les optimisations de MapStaticAssets, mais est utile pour certaines tâches que MapStaticAssets ne peut pas gérer.

Configurez l’Intergiciel de mappage de ressources statiques en appelant MapStaticAssets dans le pipeline de traitement des requêtes de l’application qui effectue ce qui suit :

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

MapStaticAssets peut remplacer UseStaticFiles dans la plupart des situations. Toutefois, MapStaticAssets est optimisé pour distribuer les ressources 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é.

MapStaticAssets remplace l’appel de UseBlazorFrameworkFiles dans les applications qui servent des fichiers d’infrastructure Blazor WebAssembly, et l’appel de UseBlazorFrameworkFiles explicite dans une Blazor Web App n’est pas nécessaire, car l’API est automatiquement appelée lors de l’appel de AddInteractiveWebAssemblyComponents.

MapStaticAssets offre les avantages suivants qui ne sont pas disponibles lorsque vous appelez 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.

L’intergiciel Mappage des ressources statiques ne fournit pas de fonctionnalités pour la minification ou 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 que MapStaticAssets ne peut pas gérer :

Consommer des ressources avec l’intergiciel Mappage des fichiers statiques

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

Les ressources sont consommées via la propriété ComponentBase.Assets, qui résout l’URL ayant fait l’objet d’une empreinte numérique d’une ressource donnée. Dans l’exemple suivant, Bootstrap, la feuille de style d’application de modèle de projet Blazor (app.css) et la feuille de style d’isolation CSS sont liés dans un composant racine, généralement le composant App (Components/App.razor) :

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

Cartes d’import

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

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

<ImportMap />

Si une ImportMapDefinition personnalisée n’est pas affectée à un composant ImportMap, la carte d’import est généré 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"
  }
}

Configurez l’Intergiciel de fichiers statiques pour délivrer des ressources statiques aux clients en appelant UseStaticFiles dans le pipeline de traitement des requêtes de l’application. Pour plus d’informations, consultez Fichiers statiques dans ASP.NET Core.

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.

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.

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.

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

Cette section s’applique aux applications autonomes Blazor WebAssembly et aux solutions hébergées Blazor WebAssembly.

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>, l’application cliente d’une solution hébergée ou d’une application autonome est publiée aux chemins d’accès suivants :

  • Dans le projet Server d’une solution hébergée Blazor WebAssembly : /BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/
  • Dans une application autonome Blazor WebAssembly : /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/

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

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

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

Dans la sortie publiée :

  • Chemin d’accès à l’application cliente dans le projet Server d’une solution hébergée Blazor WebAssembly : /BlazorHostedSample/Server/bin/Release/{TFM}/publish/wwwroot/app1/
  • Chemin d’accès à une application autonome Blazor WebAssembly : /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/

La propriété <StaticWebAssetBasePath> est couramment utilisée pour contrôler les chemins d’accès aux ressources statiques publiées de plusieurs applications Blazor WebAssembly dans un déploiement hébergé unique. Pour plus d’informations, consultez Plusieurs applications ASP.NET Core Blazor WebAssembly hébergées. La propriété est également efficace dans les applications autonomes Blazor WebAssembly.

Dans les exemples précédents, l’espace réservé {TFM} est le Moniker de 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 });

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.

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

    using Microsoft.AspNetCore.StaticFiles;

...

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

builder.Services.Configure<StaticFileOptions>(options =>
{
    options.ContentTypeProvider = provider;
});

    Cette approche configure le même fournisseur de fichiers que celui utilisé pour traiter le script Blazor. Assurez-vous que votre configuration personnalisée n’interfère pas avec le service du script Blazor. Par exemple, ne supprimez pas le mappage pour les fichiers JavaScript en configurant le fournisseur avec provider.Mappings.Remove(".js").

  • Utilisez deux appels de UseStaticFiles dans le fichier Program :

    • Configurez le fournisseur de fichiers personnalisé dans le premier appel avec StaticFileOptions.
    • Le deuxième intergiciel délivre le script Blazor, qui utilise la configuration de fichiers statiques par défaut fournie par l’infrastructure Blazor.
    using Microsoft.AspNetCore.StaticFiles;

...

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

app.UseStaticFiles(new StaticFileOptions { ContentTypeProvider = provider });
app.UseStaticFiles();

  • Vous pouvez éviter d’interférer avec le service _framework/blazor.server.js en utilisant MapWhen pour exécuter un Intergiciel de fichier statique personnalisé :

    app.MapWhen(ctx => !ctx.Request.Path
    .StartsWithSegments("/_framework/blazor.server.js"),
        subApp => subApp.UseStaticFiles(new StaticFileOptions() { ... }));

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 :

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