Freigeben über

Bereitstellen und Hosten eines eigenständigen ASP.NET Core Blazor WebAssembly mit GitHub Pages

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Informationen zum aktuellen Release finden Sie in der .NET 9-Version dieses Artikels.

Warnung

Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der .NET- und .NET Core-Supportrichtlinie. Informationen zum aktuellen Release finden Sie in der .NET 9-Version dieses Artikels.

Wichtig

Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Informationen zum aktuellen Release finden Sie in der .NET 9-Version dieses Artikels.

In diesem Artikel wird erläutert, wie Sie eigenständige Apps Blazor WebAssembly mithilfe von GitHub-Seiten hosten und bereitstellen.

Die folgende Anleitung für GitHub-Pages-Bereitstellungen von Blazor WebAssembly-Apps veranschaulicht Konzepte mit einem Live-Tool, das auf GitHub Pages bereitgestellt wird. Das Tool wird von den Autoren der ASP.NET Core-Dokumentation verwendet, um Querverweislinks (XREF) zu API-Dokumentationen für Artikel-Markdown zu erstellen.

GitHub Pages Einstellungen

  • Aktionen>Allgemein
    • Actions-Berechtigungen
      • Unternehmensaktionen zulassen sowie nicht-unternehmenseigene Aktionen und wiederverwendbare Workflows auswählen> Aktiviert (ausgewählt)
      • Von GitHub erstellte Aktionen zulassen> Aktiviert (ausgewählt)
      • Zulassen von Aktionen und wiederverwendbaren Workflows>stevesandersonms/ghaction-rewrite-base-href@{SHA HASH},†
    • Workflow-Berechtigungen>Berechtigungen zum Lesen von Repository-Inhalten und -Paketen
  • Pages>Build & Deployment
    • Quelle>GitHub Actions
    • Ausgewählter Workflow: Statisches HTML und erstellen Sie Ihr Skript für statische Bereitstellungsaktionen auf der Grundlage der Xref-Generator-static.ymlDatei für das Xref-Generator-Tool. Die Konfiguration in der Datei wird im nächsten Abschnitt beschrieben.
    • Benutzerdefinierte Domäne: Legen Sie fest, ob Sie eine benutzerdefinierte Domäne verwenden möchten, die von dieser Anleitung nicht abgedeckt wird. Weitere Informationen findest du unter Konfigurieren einer benutzerdefinierten Domäne für deine GitHub Pages-Website.
    • HTTPS erzwingen> Aktiviert (ausgewählt)

†Der SHA-Hash ({SHA HASH} Platzhalter) stellt den SHA-Hash für die neueste stevesandersonms/ghaction-rewrite-base-href GitHub Action-Version dar. Durch das Anheften an eine bestimmte Version besteht ein geringeres Risiko, dass eine kompromittierte neueste Version mit einem Versionsmoniker, z. B. v1, die Bereitstellung gefährden kann. Aktualisieren Sie die SHA in regelmäßigen Abständen auf die neueste Version für die neuesten Features und Fehlerbehebungen.

So rufen Sie den SHA-Hash ab:

  1. Navigieren Sie zum SteveSandersonMS/ghaction-rewrite-base-href GitHub-Repository "Action".
  2. Wählen Sie die Version auf der rechten Seite der Seite unter "Versionen" aus.
  3. Suchen und auswählen Sie den kurzen SHA-Hash (z. B 5b54862. ).
  4. Entweder:
    • Übernehmen Sie die vollständige SHA aus der URL in der Adressleiste des Browsers.
    • Wählen Sie die Schaltfläche "Kopieren" auf der rechten Seite der Seite Schaltfläche aus, um das SHA auf die Zwischenablage zu legen.

Weitere Informationen finden Sie unter Verwenden vordefinierter Bausteine in Ihrem Workflow: Verwenden von SHAs (GitHub-Dokumentation).

Konfiguration eines statischen Bereitstellungsskripts

Xref-Generator static.yml Datei

Konfigurieren Sie die folgenden Einträge im Skript für Ihre Bereitstellung:

  • Veröffentlichungsverzeichnis (PUBLISH_DIR): Verwenden Sie den Pfad zum Ordner des Repositorys, in dem die Blazor WebAssembly-App veröffentlicht wird. Die App wird für eine bestimmte .NET-Version kompiliert, und das Pfadsegment für die Version muss übereinstimmen. Beispiel: BlazorWebAssemblyXrefGenerator/bin/Release/net9.0/publish/wwwroot ist der Pfad für eine App, die das net9.0Target Framework Moniker (TFM) für das .NET 9 SDK verwendet.
  • Pushpfad (on:push:paths): Legen Sie den Pushpfad so fest, dass er dem Repository-Ordner der App mit einem **-Wildcard entspricht. Beispiel: BlazorWebAssemblyXrefGenerator/**.
  • .NET SDK-Version (dotnet-version über die actions/setup-dotnet Action): Derzeit gibt es keine Möglichkeit, die Version auf "neueste Version" festzulegen (siehe Zulassen der Angabe von "neueste" als dotnet-version (actions/setup-dotnet #497), um die Featureanforderung zu unterstützen). Legen Sie die SDK-Version mindestens so hoch wie die Frameworkversion der App fest.
  • Veröffentlichungspfad (dotnet publish-Befehl): Setzen Sie den Veröffentlichungspfad auf den Ordner des App-Repos. Beispiel: dotnet publish BlazorWebAssemblyXrefGenerator -c Release.
  • Base-HREF (base_href für die SteveSandersonMS/ghaction-rewrite-base-href-Aktion): Setzen Sie den SHA-Hash für die neueste Version der Aktion (siehe die Anweisungen im Abschnitt Einstellungen von GitHub Pages für weitere Informationen). Legen Sie das Basis-Href für die App auf den Namen des Repositorys fest. Beispiel: Der Blazor Repositorybesitzer des Beispiels ist dotnet. Der Blazor Name des Repositorys des Beispiels ist blazor-samples. Wenn das Xref-Generator-Tool auf GitHub-Seiten bereitgestellt wird, basiert die Webadresse auf dem Namen des Repositorys (https://dotnet.github.io/blazor-samples/). Der Basis-Href der App ist /blazor-samples/, der in base_href für die ghaction-rewrite-base-href-Aktion festgelegt ist, um in den wwwroot/index.html<base>-Tag der App zu schreiben, wenn die App bereitgestellt wird. Weitere Informationen finden Sie unter ASP.NET Core-App-BasispfadBlazor.

Der GitHub-gehostete Ubuntu-Server (neueste Version) hat eine Version des .NET SDK vorinstalliert. Sie können den Schritt actions/setup-dotnet Aktion aus dem Skript static.yml entfernen, wenn das vorinstallierte .NET SDK ausreicht, um die App zu kompilieren. So ermitteln Sie das .NET SDK, das für ubuntu-latest installiert ist:

  1. Wechseln Sie zum Abschnitt Verfügbare Bilder des actions/runner-images GitHub-Repositorys.
  2. Suchen Sie die Abbildung ubuntu-latest, die die erste Tabellenzeile darstellt.
  3. Wählen Sie den Link in der Included Software-Spalte aus.
  4. Scrollen Sie nach unten zum Abschnitt .NET Tools, um das mit dem Image installierte .NET Core SDK anzuzeigen.

Notizen zur Implementierung

Die Standardaktion von GitHub, die Seiten bereitstellt, überspringt die Bereitstellung von Ordnern, die mit einem Unterstrich beginnen, z. B. der Ordner _framework. Zum Bereitstellen von Ordnern, die mit Unterstrich beginnen, fügen Sie dem Stammverzeichnis des App-Repositorys eine leere Datei namens .nojekyll hinzu. Beispiel: Xref-Generator .nojekyll Datei

Führen Sie diesen Schritt vor der ersten App-Bereitstellung aus: Git behandelt JavaScript (JS)-Dateien, wie blazor.webassembly.js als Text und konvertiert Zeilenenden von CRLF (Carriage Return-Line Feed) zu LF (Line Feed) in der Bereitstellungspipeline. Diese Änderungen an JS Dateien erzeugen unterschiedliche Dateihashes im Vergleich zu denen, die Blazor an den Client sendet. Die Konflikte führen zu Fehlern der Integritätsprüfung auf dem Client. Ein Ansatz zum Beheben dieses Problems besteht darin, eine .gitattributes-Datei mit einer Zeile *.js binary hinzuzufügen, bevor die Ressourcen der App dem Git-Branch hinzugefügt werden. Die *.js binary Zeile konfiguriert Git so, dass JS Dateien als Binärdateien behandelt werden, wodurch die Verarbeitung der Dateien in der Bereitstellungspipeline vermieden wird und clientseitige Integritätsprüfungen erfolgreich bestehen. Weitere Informationen finden Sie unter ASP.NET Core Blazor WebAssembly .NET Bundle Caching- und Integritätsprüfungsfehler. Beispiel: Xref-Generator .gitattributes Datei

Zur Behandlung von URL-Umschreibungen basierend auf Single-Page-Apps für GitHub Pages (rafrex/spa-github-pages GitHub Repository):

GitHub Pages unterstützt die Verwendung von Brotli-komprimierten Ressourcen nicht nativ. So verwenden Sie Brotli: