Archivos estáticos Blazor en ASP.NET Core

En este artículo se describe la configuración de la aplicación Blazor para servir archivos estáticos.

Entrega de recursos estáticos en aplicaciones del lado Blazor servidor

El servicio de recursos estáticos se administra mediante convenciones de punto de conexión de enrutamiento o un middleware descrito en la tabla siguiente.

Característica	API	Versión de .NET	Descripción
Asignación de convenciones de punto de conexión de enrutamiento de recursos estáticos	MapStaticAssets	.NET 9 o posterior	Optimiza la entrega de recursos estáticos a los clientes.
Middleware de archivos estáticos	UseStaticFiles	Todas las versiones de .NET	Proporciona recursos estáticos a los clientes sin las optimizaciones de los recursos estáticos de asignación, pero útiles para algunas tareas que asignan recursos estáticos no son capaces de administrar.

Configure Map Static Assets mediante una llamada a MapStaticAssets en la canalización de procesamiento de solicitudes de la aplicación, que realiza lo siguiente:

• Establece los encabezados ETag y Last-Modified.
• Establece encabezados de almacenamiento en caché.
• Usa Middleware de almacenamiento en caché.
• Cuando sea posible, sirve recursos estáticos comprimidos.
• Funciona con una Red de entrega de contenido (CDN) (por ejemplo, Azure CDN) para atender los recursos estáticos de la aplicación más cerca del usuario.
• Huella digital de activos para evitar la reutilización de versiones antiguas de archivos.

Map Static Assets funciona combinando procesos de compilación y publicación para recopilar información sobre los recursos estáticos de la aplicación. La biblioteca en runtime utiliza esta información para servir eficazmente los recursos estáticos a los exploradores.

Asignar activos estáticos puede reemplazar UseStaticFiles en la mayoría de las situaciones. Sin embargo, los recursos estáticos de asignación están optimizados para atender los recursos desde ubicaciones conocidas de la aplicación en tiempo de compilación y publicación. Si la aplicación atiende recursos de otras ubicaciones, como el disco o los recursos incrustados, debe usarse UseStaticFiles.

Map Static Assets (MapStaticAssets) reemplaza la llamada UseBlazorFrameworkFiles a en aplicaciones que atienden Blazor WebAssembly archivos de marco y no es necesario llamar UseBlazorFrameworkFiles explícitamente a en porque Blazor Web App se llama automáticamente a la API al invocar AddInteractiveWebAssemblyComponents.

Asignar recursos estáticos proporciona las siguientes ventajas que no están disponibles al llamar a UseStaticFiles:

• Compresión durante la compilación de todos los activos de la aplicación, incluidos JavaScript (JS) y las hojas de estilo, pero excluyendo los activos de imágenes y fuentes que ya están comprimidos. Durante el desarrollo se utiliza la compresión Gzip (Content-Encoding: gz). Durante la publicación se utiliza la compresión Gzip con Brotli (Content-Encoding: br).
• Huella digital para todos los activos en runtime con una cadena codificada en Base64 del hash SHA-256 del contenido de cada archivo. De este modo, se evita reutilizar una versión antigua de un archivo, aunque el archivo antiguo esté almacenado en caché. Los activos con huella digital se almacenan en caché mediante la immutable directiva, lo que hace que el navegador no vuelva a solicitar el activo hasta que cambie. Para los navegadores que no soportan la directiva immutable, se agrega una max-age directiva.
  • Incluso si un activo no tiene huella digital, un contenido basado ETags se genera para cada activo estático utilizando el hash de la huella digital del archivo como valor ETag. Esto garantiza que el navegador solo descargue un archivo si su contenido cambia (o si el archivo se descarga por primera vez).
  • Internamente, Blazor asigna los activos físicos a sus huellas dactilares, lo que permite a la aplicación:
    • Busque activos Blazor generados automáticamente, como CSS con ámbito de componente Razor para la función Blazor de aislamiento de CSS de y JS activos descritos por JS mapas de importación.
    • Generar etiquetas de vínculo en el contenido <head> de la página para precargar activos.
• Durante las pruebas de desarrollo de Recarga activa de Visual Studio:
  • La información de integridad se elimina de los activos para evitar problemas cuando se modifica un archivo mientras se ejecuta la aplicación.
  • Los activos estáticos no se almacenan en caché para garantizar que el navegador siempre recupere el contenido actual.

Cuando están habilitados los modos WebAssembly Interactivo o Auto renderizado Interactivo:

• Blazor crea un punto de conexión para exponer la colección de recursos como un módulo JS.
• La URL se emite en el cuerpo de la solicitud como estado persistente del componente cuando un componente WebAssembly se renderiza en la página.
• Durante el arranque de WebAssembly, Blazor recupera la URL, importa el módulo y llama a una función para recuperar la colección de activos y reconstruirla en memoria. La URL es específica del contenido y se almacena en caché para siempre, por lo que este coste general solo se paga una vez por usuario hasta que se actualiza la aplicación.
• La colección de recursos también se expone en una URL legible por humanos (_framework/resource-collection.js), por lo que JS tiene acceso a la colección de recursos para mejorar la navegación o para implementar características de otros frameworks y componentes de terceros.

Los recursos estáticos de asignación no proporcionan características para la minificación u otras transformaciones de archivo. La minificación suele realizarse mediante código personalizado o herramientas de terceros.

El middleware de archivos estáticos (UseStaticFiles) es útil en las siguientes situaciones que no pueden controlar los recursos estáticos de asignación (MapStaticAssets):

• Aplicación de un prefijo de ruta a Blazor WebAssemblyarchivos de activos estáticos, que se trata en la sección Prefijo para Blazor WebAssembly activos .
• Configurar asignaciones de archivos de extensiones a tipos de contenido específicos y establecer opciones de archivo estático, que se tratan en la secciónAsignaciones de archivos y opciones de archivo estático.

Para obtener más información, vea Archivos estáticos en ASP.NET Core.

Entrega de recursos con convenciones de punto de conexión de enrutamiento de recursos estáticos de asignación

Esta sección se aplica a las aplicaciones Blazor del lado del servidor.

Los recursos se entregan a través de la ComponentBase.Assets propiedad , que resuelve la dirección URL con huella digital de un recurso determinado. En el ejemplo siguiente, Bootstrap, la Blazor hoja de estilos de la aplicación de plantilla de proyecto (app.css) y la hoja de estilos de aislamiento css (basada en el espacio de nombres de una aplicación de BlazorSample) están vinculadas en un componente raíz, normalmente el App componente (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"]" />

Importación de mapas

Esta sección se aplica a las aplicaciones Blazor del lado del servidor.

El componente Importar mapa (ImportMap) representa un elemento de mapa de importación (<script type="importmap"></script>) que define el mapa de importación para los scripts de módulo. El componente Importar mapa se coloca en <head> el contenido del componente raíz, normalmente el App componente (Components/App.razor).

<ImportMap />

Si no se asigna un elemento personalizado ImportMapDefinition a un componente importar mapa, el mapa de importación se genera en función de los recursos de la aplicación.

Los siguientes ejemplos muestran definiciones de asignación de importación personalizadas y las asignaciones de importación que crean.

Asignación básica de importación:

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

El código anterior da como resultado la siguiente asignación de importación:

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

Asignación básica de ámbito:

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

El código anterior da como resultado la siguiente asignación de importación:

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

Importación de asignación con integridad:

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" },
    });

El código anterior da como resultado la siguiente asignación de importación:

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

Combinar definiciones de asignación de importación (ImportMapDefinition) con ImportMapDefinition.Combine.

Asignación de importación creada a partir de un ResourceAssetCollection que asigna activos estáticos a sus correspondientes URL únicas:

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

El código anterior da como resultado la siguiente asignación de importación:

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

En versiones anteriores a .NET 8, los archivos estáticos del marco Blazor, como el script de Blazor, se sirven mediante el middleware de archivos estáticos. En .NET 8 o versiones posteriores, los archivos estáticos del marco Blazor se asignan mediante el enrutamiento de puntos de conexión y ya no se usa middleware de archivos estáticos.

Resumen de formatos <link> href de archivos estáticos

Esta sección se aplica a todas las versiones Blazor y aplicaciones .NET.

En las tablas siguientes se resumen los formatos de archivos estáticos <link> href por versión de .NET.

Para conocer la ubicación del contenido <head> donde se colocan los enlaces a archivos estáticos, consulte Estructura del proyecto ASP.NET Core Blazor. Los vínculos de activos estáticos también pueden suministrarse utilizando <HeadContent> componentes en componentes Razor individuales.

.NET 9 o posterior

Tipo de aplicación	Valor de href	Ejemplos
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" />
Independiente Blazor WebAssembly	{PATH}	<link rel="stylesheet" href="css/app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 8.x

Tipo de aplicación	Valor de href	Ejemplos
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" />
Independiente Blazor WebAssembly	{PATH}	<link rel="stylesheet" href="css/app.css" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />

.NET 7.x o versiones anteriores

Tipo de aplicación	Valor de href	Ejemplos
Blazor Server†	{PATH}	<link href="css/site.css" rel="stylesheet" /> <link href="_content/ComponentLib/styles.css" rel="stylesheet" />
Hospedado 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 es compatible con .NET 8 o posterior, pero ya no es una plantilla de proyecto después de .NET 7.
‡Recomendamos actualizar las aplicaciones Blazor WebAssembly hospedadas a Blazor Web App cuando se adopte .NET 8 o una versión posterior.

Modo de proyecto de activos web estáticos

Esta sección se aplica al proyecto .Client de una Blazor Web App.

La configuración <StaticWebAssetProjectMode>Default</StaticWebAssetProjectMode> necesaria en el proyecto .Client de una Blazor Web App revierte los comportamientos de recursos estáticos de Blazor WebAssembly a los valores predeterminados, de modo que el proyecto se comporte como parte del proyecto hospedado. El SDK Blazor WebAssembly (Microsoft.NET.Sdk.BlazorWebAssembly) configura los recursos web estáticos de una manera específica de trabajar en modo "independiente" con un servidor que simplemente consume las salidas de la biblioteca. Esto no es adecuado para un objeto Blazor Web App, donde la parte WebAssembly de la aplicación es una parte lógica del host y debe comportarse más como una biblioteca. Por ejemplo, el proyecto no expone el conjunto de estilos (por ejemplo, BlazorSample.Client.styles.css) y, en su lugar, solo proporciona el host con el lote de proyectos, para que el host pueda incluirlo en su propio conjunto de estilos.

Cambiar el valor (Default) de <StaticWebAssetProjectMode> o quitar la propiedad del proyecto .Client no se admite.

Archivos estáticos en entornos que no son de Development

Esta sección se aplica a los archivos estáticos del lado servidor.

Cuando se ejecuta una aplicación localmente, los recursos web estáticos solo están habilitados en el entorno de Development. Para habilitar los archivos estáticos para los entornos distintos de Development durante el desarrollo y las pruebas locales (por ejemplo, Staging), llama a UseStaticWebAssets en el WebApplicationBuilder del archivo Program.

Advertencia

Llama UseStaticWebAssets al entorno exacto para evitar la activación de la característica en producción, ya que sirve archivos de ubicaciones independientes en el disco que no sean del proyecto si se llama en un entorno de producción. En el ejemplo de esta sección se comprueba el entorno de Staging llamando a IsStaging.

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

Prefijo para recursos de Blazor WebAssembly

Esta sección es aplicable a Blazor Web App.

Usa la opción WebAssemblyComponentsEndpointOptions.PathPrefix punto de conexión para establecer la cadena de ruta de acceso que indica el prefijo para los recursos de Blazor WebAssembly. La ruta de acceso debe corresponder a un proyecto de aplicación de Blazor WebAssembly al que se hace referencia.

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

En el ejemplo anterior, el marcador de posición {PATH PREFIX} es el prefijo de ruta de acceso y debe comenzar con una barra diagonal (/).

En el ejemplo siguiente, el prefijo de ruta de acceso se establece en /path-prefix:

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

Ruta de acceso base del recurso web estático

Esta sección se aplica a las aplicaciones Blazor WebAssembly independientes.

La publicación de una aplicación coloca sus recursos estáticos, incluidos los archivos de marco de Blazor (recursos de la carpeta _framework), en la ruta raíz (/) en la salida publicada. La propiedad <StaticWebAssetBasePath> especificada en el archivo de proyecto (.csproj) establece la ruta de acceso base en una ruta de acceso no raíz:

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

En el ejemplo anterior, el marcador de posición {PATH} es la ruta de acceso.

Sin establecer la propiedad <StaticWebAssetBasePath>, se publica una aplicación independiente en /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/.

En los ejemplos anteriores, el marcador de posición {TFM} es el Moniker de la plataforma de destino (TFM) (por ejemplo, net6.0).

Si la propiedad <StaticWebAssetBasePath> en una aplicación Blazor WebAssembly independiente establece la ruta del recurso estático publicado en app1, la ruta raíz a la aplicación en la salida publicada es /app1.

En el archivo de proyecto de la aplicación independiente Blazor WebAssembly (.csproj):

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

En la salida publicada, la ruta de acceso a la aplicación independiente Blazor WebAssembly es /BlazorStandaloneSample/bin/Release/{TFM}/publish/wwwroot/app1/.

En los ejemplos anteriores, el marcador de posición {TFM} es el Moniker de la plataforma de destino (TFM) (por ejemplo, net6.0).

Asignaciones de archivos y opciones de archivo estático

Esta sección se aplica a los archivos estáticos del lado servidor.

Para crear asignaciones de archivos adicionales con un objeto FileExtensionContentTypeProvider o configurar otros valores StaticFileOptions, use uno de los enfoques siguientes. En los ejemplos siguientes, el marcador de posición {EXTENSION} es la extensión de archivo y {CONTENT TYPE} es el tipo de contenido. El espacio de nombres de la API siguiente es Microsoft.AspNetCore.StaticFiles.

• Configure las opciones a través de la inserción de dependencias (DI) en el archivo Program mediante StaticFileOptions:

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

• Pasa StaticFileOptions directamente a UseStaticFiles en el archivo Program:

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

Entrega de archivos desde varias ubicaciones

La guía de esta sección es aplicable solo a Blazor Web App.

Para proporcionar archivos desde varias ubicaciones con un CompositeFileProvider:

• Agregue el espacio de nombres para Microsoft.Extensions.FileProviders en la parte superior del archivo Program del proyecto de servidor.
• En el archivo Program del proyecto de servidor antesde la llamada a UseStaticFiles:
  • Cree un PhysicalFileProvider con la ruta de acceso a los recursos estáticos.
  • Cree un CompositeFileProvider a partir del WebRootFileProvider y el PhysicalFileProvider. Vuelva a asignar el proveedor de archivos compuesto al WebRootFileProviderde la aplicación.

Ejemplo:

Cree una carpeta en el proyecto de servidor denominada AdditionalStaticAssets. Coloque una imagen en la carpeta.

Agregue la siguiente instrucción using a la parte superior del archivo Program del proyecto de servidor:

using Microsoft.Extensions.FileProviders;

En el archivo Program del proyecto de servidor antesde la llamada a UseStaticFiles, agregue el siguiente código:

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

En el componente Home de la aplicación (Home.razor) marcado, haga referencia a la imagen con una etiqueta <img>:

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

En el ejemplo anterior:

• El marcador de posición {IMAGE FILE NAME} es el nombre del archivo de imagen. No es necesario proporcionar un segmento de ruta de acceso si el archivo de imagen está en la raíz de la carpeta AdditionalStaticAssets.
• El marcador de posición {ALT TEXT} es el texto alternativo de la imagen.

Ejecutar la aplicación.

Recursos adicionales

• Ruta de acceso base de la aplicación
• Evitar la captura de archivos en un parámetro de ruta