Compartir a través de

Hospedar e implementar ASP.NET Core independiente Blazor WebAssembly con GitHub Pages

Nota:

Esta no es la versión más reciente de este artículo. Para la versión actual, consulte la versión de .NET 9 de este artículo.

Advertencia

Esta versión de ASP.NET Core ya no se admite. Para más información, consulte la directiva de soporte técnico de .NET y .NET Core. Para la versión actual, consulte la versión de .NET 9 de este artículo.

Importante

Esta información hace referencia a un producto en versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no ofrece ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.

Para la versión actual, consulte la versión de .NET 9 de este artículo.

En este artículo se explica cómo hospedar e implementar de forma independiente Blazor WebAssembly mediante GitHub Pages.

Las siguientes guías para las implementaciones de GitHub Pages de aplicaciones Blazor WebAssembly muestran conceptos con una herramienta activa implementada en GitHub Pages. La herramienta la utilizan los autores de documentación de ASP.NET Core para crear vínculos de referencia cruzada (XREF) a la documentación de API en los documentos de Markdown.

Configuración de GitHub Pages

  • Acciones>General
    • Permisos de Actions
      • Permitir acciones empresariales y seleccionar acciones no empresariales y flujos de trabajo reutilizables> Habilitado (seleccionado)
      • Permitir acciones creadas por GitHub> Habilitado (seleccionado)
      • Permitir acciones y flujos de trabajo reutilizables>stevesandersonms/ghaction-rewrite-base-href@{SHA HASH},†
    • permisos de flujo de trabajo>permisos para leer el contenido del repositorio y los paquetes
  • Pages>Compilación e Implementación
    • Origen>GitHub Actions
    • Flujo de trabajo seleccionado: HTML estático y basar el script de Action de implementación estática en el archivo de generador de referencias cruzadasstatic.yml para la herramienta Generador de referencias cruzadas. La configuración del archivo se describe en la sección siguiente.
    • dominio personalizado: establezca si piensa usar un dominio personalizado, que no está cubierto por esta guía. Para obtener más información, consulte Configuración de un dominio personalizado para el sitio de GitHub Pages.
    • Aplicar HTTPS> Habilitado (seleccionado)

†El hash SHA (marcador de posición {SHA HASH}) representa el hash SHA para la versión más reciente de la acción de GitHub stevesandersonms/ghaction-rewrite-base-href. Al anclar a una versión específica, existe menos riesgo de que una versión más reciente comprometida con un identificador de versión, como v1, ponga en peligro la implementación. Periódicamente, actualice el SHA a la versión más reciente para las características y correcciones de errores más recientes.

Para obtener el hash SHA:

  1. Vaya al repositorio de GitHub SteveSandersonMS/ghaction-rewrite-base-href Acción.
  2. Seleccione la versión en el lado derecho de la página en Versiones.
  3. Busque y seleccione el hash sha corto (por ejemplo, 5b54862).
  4. Tener instaladas localmente una de las siguientes:
    • Tome el SHA completo de la dirección URL en la barra de direcciones del explorador.
    • Seleccione el botón Copiar situado a la derecha de la página botón Copiar para copiar el SHA en tu portapapeles.

Para obtener más información, consulte Uso de bloques de construcción preescritos en su flujo de trabajo: Uso de SHAs (documentación de GitHub).

Configuración del script de implementación estática

Archivo de generador de referencias cruzadas static.yml

Configure las siguientes entradas en el script para la implementación:

  • Publicar directorio (PUBLISH_DIR): use la ruta de acceso a la carpeta del repositorio donde se publica la aplicación Blazor WebAssembly. La aplicación se compila para una versión específica de .NET y el segmento de la ruta de la versión debe coincidir. Ejemplo: BlazorWebAssemblyXrefGenerator/bin/Release/net9.0/publish/wwwroot es la ruta de acceso de una aplicación que adopta el net9.0Moniker de la plataforma de destino (TFM) para el SDK de .NET 9.
  • Ruta de acceso de inserción (on:push:paths): configure la ruta de acceso de inserción para que coincida con la carpeta del repositorio de la aplicación utilizando un carácter comodín **. Ejemplo: BlazorWebAssemblyXrefGenerator/**.
  • Versión del SDK de .NET (dotnet-version a través de la acción actions/setup-dotnet): actualmente, no hay manera de establecer la versión en "latest" (consulte Permitir especificar "latest" como dotnet-version (actions/setup-dotnet #497) para votar a favor de la solicitud). Establezca la versión del SDK al menos tan alta como la versión del marco de trabajo de la aplicación.
  • Ruta de acceso de publicación (comandodotnet publish): configure la ruta de la carpeta de publicación a la carpeta del repositorio de la aplicación. Ejemplo: dotnet publish BlazorWebAssemblyXrefGenerator -c Release.
  • HREF base (base_href para la Acción SteveSandersonMS/ghaction-rewrite-base-href de): Establezca el hash SHA para la versión más reciente de la Acción. Consulte las instrucciones en la sección de configuración de Páginas de GitHubs para saber más. Establezca el href base de la aplicación en el nombre del repositorio. Ejemplo: el propietario del repositorio del ejemplo de Blazor es dotnet. El nombre del repositorio del ejemplo de Blazor es blazor-samples. Cuando la herramienta Generador Xref se implementa en GitHub Pages, su dirección web se basa en el nombre del repositorio (https://dotnet.github.io/blazor-samples/). El href base de la aplicación es /blazor-samples/, que se establece en base_href para que la acción ghaction-rewrite-base-href escriba en la etiqueta wwwroot/index.html<base> de la aplicación cuando se implemente. Para obtener más información, consulte ASP.NET Core Blazor app base path.

El servidor ubuntu hospedado en GitHub (más reciente) tiene una versión del SDK de .NET preinstalado. Puede eliminar el paso de acción actions/setup-dotnet del script static.yml si el SDK de .NET preinstalado es suficiente para compilar la aplicación. Para determinar el SDK de .NET instalado para ubuntu-latest:

  1. Vaya a la sección Imágenes disponibles del repositorio de GitHub actions/runner-images.
  2. Busque la imagen ubuntu-latest, que es la primera fila de la tabla.
  3. Seleccione el vínculo de la columna Included Software.
  4. Descienda hasta la sección .NET Tools para ver el SDK de .NET Core instalado con la imagen.

Notas de implementación

La acción predeterminada de GitHub, que implementa páginas, omite la implementación de carpetas que empiezan por un carácter de subrayado como, por ejemplo, la carpeta_framework. Para implementar carpetas que empiecen con el carácter de subrayado, agregue un archivo .nojekyll vacío a la raíz del repositorio de la aplicación. Ejemplo: archivo de generador de referencias cruzadas .nojekyll

Realice este paso antes de la primera implementación de la aplicación: Git trata los archivos JavaScript (JS), como blazor.webassembly.js, como texto y convierte los finales de línea de CRLF (retorno de carro y avance de línea) a LF (avance de línea) en la canalización de implementación. Estos cambios en los archivos JS generan hashes de archivo distintos de los que Blazor envía al cliente en el archivo. Las discordancias dan lugar a errores de comprobación de integridad en el cliente. Un enfoque para resolver este problema es añadir un archivo .gitattributes con la línea *.js binary antes de añadir los recursos de la aplicación a la rama de Git. La línea *.js binary configura Git para que trate los archivos JS como archivos binarios, lo que evita el procesamiento de los archivos en la pipeline de despliegue y hace que se pasen las comprobaciones de integridad del lado del cliente. Para obtener más información, consulte errores de almacenamiento en caché de paquetes de .NET y comprobación de integridad en ASP.NET CoreBlazor WebAssembly. Ejemplo: archivo de generador de referencias cruzadas .gitattributes

Para controlar las reescrituras de URL basadas en aplicaciones de página única para GitHub Pages (repositorio de GitHub rafrex/spa-github-pages):

Las páginas de GitHub no admiten de forma nativa el uso de recursos comprimidos por Brotli. Para usar Brotli: