Vorabrendern und Integrieren von ASP.NET Core Razor-Komponenten

In diesem Artikel wird die Integration von Razor-Komponenten für Blazor-Apps erklärt, einschließlich des Vorabrenderns von Razor-Komponenten auf dem Server.

Wichtig

In diesem Artikel finden Sie verschiedene Anweisungen, die aufgrund von Frameworkänderungen in ASP.NET Core-Versionen entstanden sind. Bevor Sie den Leitfaden dieses Artikels verwenden, vergewissern Sie sich, dass die Dokumentversionsauswahl oben in diesem Artikel mit der Version von ASP.NET Core übereinstimmt, die Sie für Ihre App verwenden möchten.

Razor Komponenten können in Razor Pages und MVC-Apps einer gehosteten Blazor WebAssemblyLösung integriert werden. Wenn die Seite oder Ansicht gerendert wird, können Komponenten gleichzeitig vorab gerendert werden.

Prerendering kann die Suchmaschinenoptimierung (Search Engine Optimization, SEO) verbessern, indem Inhalte für die erste HTTP-Antwort gerendert werden, die Suchmaschinen zum Berechnen des Seitenrangs verwenden können.

Projektmappenkonfiguration

Konfiguration für Vorabrendern

So richten Sie das Vorabrendern für eine gehostete Blazor WebAssembly-App ein:

1. Hosten Sie die Blazor WebAssembly-App in einer ASP.NET Core-App. Eine eigenständige Blazor WebAssembly-App kann einer ASP.NET Core-Lösung hinzugefügt werden, oder Sie können eine gehostete Blazor WebAssembly-App verwenden, die aus der Blazor WebAssembly-Projektvorlage mit der Option „Gehostet“ erstellt wurde:

   • Visual Studio: Aktivieren Sie im Dialogfeld Zusätzliche Informationen beim Erstellen einer Blazor WebAssembly-App das Kontrollkästchen Von ASP.NET Core gehostet. In den Beispielen dieses Artikels heißt die Projektmappe BlazorHosted.
   • Visual Studio Code/.NET CLI-Befehlsshell: dotnet new blazorwasm -ho (verwenden Sie die Option -ho|--hosted). Verwenden Sie die Option -o|--output {LOCATION}, um einen Ordner für die Projektmappe zu erstellen und die Projektnamespaces der Projektmappe festzulegen. In den Beispielen dieses Artikels heißt die Projektmappe BlazorHosted (dotnet new blazorwasm -ho -o BlazorHosted).

   Für die Beispiele in diesem Artikel lautet der Name der gehosteten Lösung (Assemblyname) BlazorHosted. Der Namespace des Clientprojekts lautet BlazorHosted.Client, der des Serverprojekts BlazorHosted.Server.

2. Löschen Sie die Datei wwwroot/index.html aus dem Blazor WebAssemblyClient -Projekt.

3. Löschen Sie im Projekt Client die folgenden Zeilen in Program.cs:

   - builder.RootComponents.Add<App>("#app");
   - builder.RootComponents.Add<HeadOutlet>("head::after");
   

4. Fügen Sie die Datei _Host.cshtml in den Ordner Pages des Projekts Server ein. Sie können die Dateien aus einem mit der Blazor Server-Vorlage erstellten Projekt über Visual Studio oder mit der .NET CLI mit dem Befehl dotnet new blazorserver -o BlazorServer in einer Befehlsshell abrufen (die Option -o BlazorServer erstellt einen Ordner für das Projekt). Nachdem Sie die Dateien im Ordner Pages des Server-Projekts platziert haben, nehmen Sie die folgenden Änderungen an den Dateien vor.

   Nehmen Sie an der _Host.cshtml-Datei die folgenden Änderungen vor:

   • Aktualisieren Sie den Namespace Pages am Anfang der Datei so, dass er mit dem Namespace der Seiten der App Server übereinstimmt. Der Platzhalter {APP NAMESPACE} im folgenden Beispiel stellt den Namespace der Seiten der App des Spenders dar, die die Datei _Host.cshtml bereitgestellt haben:

     Delete (Löschen):

     - @namespace {APP NAMESPACE}.Pages
     

     Hinzufügen:

     @namespace BlazorHosted.Server.Pages
     

   • Fügen Sie am Anfang der Datei eine @using-Anweisung für den Client -Namespace hinzu:

     @using BlazorHosted.Client
     

   • Aktualisieren Sie die Stylesheetlinks so, dass sie auf die Stylesheets des WebAssembly-Projekts zeigen. Im folgenden Beispiel ist der Namespace des Clientprojekts BlazorHosted.Client. Der Platzhalter {APP NAMESPACE} stellt den Namespace der App des Spenders dar, die die Datei _Host.cshtml bereitgestellt hat: Aktualisieren Sie das Taghilfsprogramm für Komponenten (<component>-Tag) für die Komponente HeadOutlet, um die Komponente vorab zu verarbeiten.

     Delete (Löschen):

     - <link href="css/site.css" rel="stylesheet" />
     - <link href="{APP NAMESPACE}.styles.css" rel="stylesheet" />
     - <component type="typeof(HeadOutlet)" render-mode="ServerPrerendered" />
     

     Hinzufügen:

     <link href="css/app.css" rel="stylesheet" />
     <link href="BlazorHosted.Client.styles.css" rel="stylesheet" />
     <component type="typeof(HeadOutlet)" render-mode="WebAssemblyPrerendered" />
     

     Hinweis

     Belassen Sie das <link>-Element, das das Bootstrap-Stylesheet anfordert (css/bootstrap/bootstrap.min.css), an seinem Platz.

   • Aktualisieren Sie die Quelle des Blazor-Skripts so, dass das clientseitige Blazor WebAssembly-Skript verwendet wird:

     Delete (Löschen):

     - <script src="_framework/blazor.server.js"></script>
     

     Hinzufügen:

     <script src="_framework/blazor.webassembly.js"></script>
     

   • Aktualisieren Sie den render-mode des Hilfsprogramms für Komponententags so, dass die App-Stammkomponente mit WebAssemblyPrerendered gerendert wird:

     Delete (Löschen):

     - <component type="typeof(App)" render-mode="ServerPrerendered" />
     

     Hinzufügen:

     <component type="typeof(App)" render-mode="WebAssemblyPrerendered" />
     

     Wichtig

     Vorabrendering wird für Authentifizierungsendpunkte (/authentication/-Pfadsegment) nicht unterstützt. Weitere Informationen finden Sie unter Zusätzliche Sicherheitsszenarien für Blazor WebAssembly in ASP.NET Core.

5. Ändern Sie in der Datei Program.cs des Projekts Server den Fallbackendpunkt von der Datei index.html in die Seite _Host.cshtml:

   Delete (Löschen):

   - app.MapFallbackToFile("index.html");
   

   Hinzufügen:

   app.MapFallbackToPage("/_Host");
   

6. Wenn die Projekte Client und Server einen oder mehrere gemeinsame Dienste während des Vorabrenderings verwenden, integrieren Sie die Dienstregistrierungen in eine Methode, die von beiden Projekten aufgerufen werden kann. Weitere Informationen finden Sie unter Abhängigkeitsinjektion in ASP.NET Core Blazor.

7. Führen Sie das Server -Projekt aus. Die gehostete Blazor WebAssembly-App wird durch das Server -Projekt für Clients vorab gerendert.

Konfiguration zum Einbetten von Razor-Komponenten in Seiten und Ansichten

Die folgenden Abschnitte und Beispiele zum Einbetten von Razor-Komponenten der ClientBlazor WebAssembly-App in Seiten und Ansichten der Server-App erfordern zusätzliche Konfiguration.

Das Server -Projekt muss die folgenden Dateien und Ordner aufweisen.

Razor Pages:

• Pages/Shared/_Layout.cshtml
• Pages/Shared/_Layout.cshtml.css
• Pages/_ViewImports.cshtml
• Pages/_ViewStart.cshtml

MVC:

• Views/Shared/_Layout.cshtml
• Views/Shared/_Layout.cshtml.css
• Views/_ViewImports.cshtml
• Views/_ViewStart.cshtml

Die obigen Dateien können durch Generieren einer App aus den ASP.NET Core-Projektvorlagen wie folgt abgerufen werden:

• Visual Studio-Tools für die Projekterstellung
• Öffnen einer Befehlsshell und Ausführen von dotnet new webapp -o {PROJECT NAME} (Razor Pages) oder dotnet new mvc -o {PROJECT NAME} (MVC) Die Option -o|--output mit einem Wert für den Platzhalter {PROJECT NAME} gibt einen Namen für die App an und erstellt einen Ordner für diese.

Aktualisieren Sie die Namespaces in der importierten Datei _ViewImports.cshtml, damit sie mit den Namespaces übereinstimmen, die vom Server -Projekt verwendet werden, das die Dateien empfängt.

Pages/_ViewImports.cshtml (Razor Pages):

@using BlazorHosted.Server
@namespace BlazorHosted.Server.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

Views/_ViewImports.cshtml (MVC):

@using BlazorHosted.Server
@using BlazorHosted.Server.Models
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

Aktualisieren Sie die importierte Layoutdatei, die Pages/Shared/_Layout.cshtml für Razor Seiten oder Views/Shared/_Layout.cshtml für MVC ist.

Löschen Sie zunächst den Titel und das Stylesheet aus dem Spenderprojekt, welches RPDonor.styles.css im folgenden Beispiel ist. Der {PROJECT NAME}-Platzhalter stellt den App-Namen des Projekts dar.

- <title>@ViewData["Title"] - {PROJECT NAME}</title>
- <link rel="stylesheet" href="~/RPDonor.styles.css" asp-append-version="true" />

Fügen Sie die Formatvorlagen des Client Projekts in die Layoutdatei ein. Im folgenden Beispiel ist der Namespace des Client -Projekts BlazorHosted.Client. Das <title>-Element kann gleichzeitig aktualisiert werden.

Platzieren Sie die folgenden Zeilen im <head> Inhalt der Layoutdatei:

<title>@ViewData["Title"] - BlazorHosted</title>
<link href="css/app.css" rel="stylesheet" />
<link rel="stylesheet" href="BlazorHosted.Client.styles.css" asp-append-version="true" />
<component type="typeof(HeadOutlet)" render-mode="WebAssemblyPrerendered" />

Das importierte Layout enthält zwei Navigationslinks: Home (Index-Seite) und Privacy. Damit die Home-Links auf die gehostete Blazor WebAssembly-App verweisen, ändern Sie die Links:

- <a class="navbar-brand" asp-area="" asp-page="/Index">{PROJECT NAME}</a>
+ <a class="navbar-brand" href="/">BlazorHosted</a>

- <a class="nav-link text-dark" asp-area="" asp-page="/Index">Home</a>
+ <a class="nav-link text-dark" href="/">Home</a>

In einer MVC-Layoutdatei:

- <a class="navbar-brand" asp-area="" asp-controller="Home" 
-     asp-action="Index">{PROJECT NAME}</a>
+ <a class="navbar-brand" href="/">BlazorHosted</a>

- <a class="nav-link text-dark" asp-area="" asp-controller="Home" 
-     asp-action="Index">Home</a>
+ <a class="nav-link text-dark" href="/">Home</a>

Aktualisieren Sie den App-Namen des <footer>-Elements. Im folgenden Beispiel wird der App-Name BlazorHosted verwendet:

- &copy; {DATE} - {DONOR NAME} - <a asp-area="" asp-page="/Privacy">Privacy</a>
+ &copy; {DATE} - BlazorHosted - <a asp-area="" asp-page="/Privacy">Privacy</a>

Im vorherigen Beispiel stellt der {DATE}-Platzhalter das Copyrightdatum in einer App dar, die über die Razor Pages- oder MVC-Projektvorlage generiert wurde.

Damit der Privacy-Link eine Datenschutzseite öffnet (Razor Pages), fügen Sie dem Server-Projekt eine Datenschutzseite hinzu.

Pages/Privacy.cshtml im Server -Projekt:

@page
@model PrivacyModel
@{
    ViewData["Title"] = "Privacy Policy";
}
<h1>@ViewData["Title"]</h1>

<p>Use this page to detail your site's privacy policy.</p>

Erstellen Sie für eine MVC-basierte Datenschutzansicht eine Datenschutzansicht im Server-Projekt.

View/Home/Privacy.cshtml im Server -Projekt:

@{
    ViewData["Title"] = "Privacy Policy";
}
<h1>@ViewData["Title"]</h1>

<p>Use this page to detail your site's privacy policy.</p>

Geben Sie im Home-Controller der MVC-App die Ansicht zurück.

Fügen Sie den folgenden Code zu Controllers/HomeController.cs hinzu:

public IActionResult Privacy()
{
    return View();
}

Wenn Sie Dateien aus der App eines Spenders importieren, müssen Sie alle Namespaces in den Dateien aktualisieren, damit sie mit denen des Projekts Server übereinstimmen (z. B. BlazorHosted.Server).

Importieren Sie statische Ressourcen in das Projekt Server aus dem Ordner wwwroot des Spenderprojekts:

• Ordner wwwroot/css und Inhalt
• Ordner wwwroot/js und Inhalt
• Ordner wwwroot/lib und Inhalt

Wenn das Spenderprojekt aus einer ASP.NET Core-Projektvorlage erstellt wird und die Dateien nicht geändert werden, können Sie den gesamten Ordner wwwroot aus dem Spenderprojekt in das Server -Projekt kopieren und die Symboldatei favicon entfernen.

Warnung

Vermeiden Sie es, die statische Ressource sowohl im Ordner Client als auch im Ordner Server wwwroot zu speichern. Wenn die gleiche Datei in beiden Ordnern vorhanden ist, wird eine Ausnahme ausgelöst, weil die statische Ressource denselben Webstammpfad aufweist. Hosten Sie daher eine statische Ressource in einem der wwwroot-Ordner, nicht in beiden.

Nachdem Sie die obige Konfiguration verwendet haben, betten Sie Razor-Komponenten in Seiten oder Ansichten des Projekts Server ein. Verwenden Sie die Anleitung in den folgenden Abschnitten dieses Artikels:

• Rendern von Komponenten auf einer Seite oder in einer Ansicht mit dem Hilfsprogramm für Komponententags
• Rendern von Komponenten auf einer Seite oder in einer Ansicht mit dem CSS-Selektor

Rendern von Komponenten auf einer Seite oder in einer Ansicht mit dem Hilfsprogramm für Komponententags

Nach der Konfiguration der Lösung, einschließlich der zusätzlichen Konfiguration, unterstützt der Komponententaghilfsprogramm zwei Rendermodi für das Rendern einer Komponente aus einer Blazor WebAssembly-App in einer Seite oder Ansicht:

• WebAssembly
• WebAssemblyPrerendered

Im folgenden Razor Pages-Beispiel wird die Komponente Counter auf einer Seite gerendert. Um die Komponente interaktiv zu gestalten, ist das Blazor WebAssembly-Skript im Renderabschnitt der Seite enthalten. Um die Verwendung des vollständigen Namespaces für die Counter-Komponente mit dem Komponenten-Taghilfsprogramm ({ASSEMBLY NAME}.Pages.Counter) zu vermeiden, fügen Sie eine @using-Anweisung für den Pages-Namespace des Clientprojekts hinzu. Im folgenden Beispiel ist der Namespace des Client -Projekts BlazorHosted.Client.

Im Server -Projekt, Pages/RazorPagesCounter1.cshtml:

@page
@using BlazorHosted.Client.Pages

<component type="typeof(Counter)" render-mode="WebAssemblyPrerendered" />

@section Scripts {
    <script src="_framework/blazor.webassembly.js"></script>
}

Führen Sie das Server -Projekt aus. Navigieren Sie zur Razor-Seite unter /razorpagescounter1. Die vorab gerenderte Counter-Komponente ist in die Seite eingebettet.

RenderMode konfiguriert folgende Einstellungen für die Komponente:

• Ob die Komponente zuvor für die Seite gerendert wird
• Ob die Komponente als statische HTML auf der Seite gerendert wird oder ob sie die nötigen Informationen für das Bootstrapping einer Blazor-App über den Benutzer-Agent enthält.

Weitere Informationen zum Hilfsprogramm für Komponententags, einschließlich Übergabe von Parametern und Konfiguration von RenderMode, finden Sie unter Taghilfsprogramm für Komponenten in ASP.NET Core.

Je nachdem, welche statischen Ressourcen die Komponenten verwenden und wie die Layoutseiten in einer App organisiert sind, können zusätzliche Arbeitsschritte erforderlich sein. Normalerweise werden Skripts zum Scripts-Renderabschnitt einer Seite oder Ansicht und Stylesheets zum <head>-Elementinhalt des Layouts hinzugefügt.

Festlegen von untergeordnetem Inhalt über ein Renderfragment

Vom Taghilfsprogramm für Komponenten wird der Empfang eines RenderFragment-Delegaten für untergeordneten Inhalt (z. B param-ChildContent="...") nicht unterstützt. Es wird empfohlen, eine Razor-Komponente (.razor) zu erstellen, mit der auf die Komponente verwiesen wird, die mit dem zu übergebenden untergeordneten Inhalt gerendert werden soll, und anschließend die Razor-Komponente über die Seite oder Ansicht aufzurufen.

Stellen Sie sicher, dass vorab gerenderte Komponenten der obersten Ebene bei der Veröffentlichung nicht abgeschnitten werden.

Wenn ein Taghilfsprogramm für Komponenten über eine Bibliothek, die bei der Veröffentlichung abgeschnitten wird, direkt auf eine Komponente verweist, wird die Komponente möglicherweise abgeschnitten, da es im clientseitigen App-Code keine Verweise darauf gibt. Daher wird die Komponente nicht vorab gerendert, wodurch in der Ausgabe eine leere Stelle entsteht. Weisen Sie in diesem Fall den Trimmer durch Hinzufügen eines DynamicDependency-Attributs zu einer Klasse in der clientseitigen App an, die Bibliothekskomponente zu erhalten. Wenn eine Komponente mit dem Namen SomeLibraryComponentToBePreserved erhalten bleiben soll, fügen Sie jeder Komponente Folgendes hinzu:

@using System.Diagnostics.CodeAnalysis
@attribute [DynamicDependency(DynamicallyAccessedMemberTypes.All, 
    typeof(SomeLibraryComponentToBePreserved))]

Der vorgenannte Ansatz ist in der Regel nicht erforderlich, da die App in der Regel ihre Komponenten vorgerendert hat (die nicht abgeschnitten werden), die ihrerseits auf Komponenten aus Bibliotheken verweisen (wodurch diese ebenfalls nicht abgeschnitten werden). Verwenden Sie DynamicDependency explizit nur für das direkte Vorabrendering einer Bibliothekskomponente, wenn die Bibliothek abgeschnitten wird.

Rendern von Komponenten auf einer Seite oder in einer Ansicht mit dem CSS-Selektor

Fügen Sie nach Konfiguration der Lösung, einschließlich der zusätzlichen Konfiguration, Stammkomponenten zum Client-Projekt einer gehosteten Blazor WebAssembly-Lösung in der Datei Program.cs hinzu. Im folgenden Beispiel wird die Komponente Counter als Stammkomponente mit einem CSS-Selektor deklariert, der das Element mit der id auswählt, die mit counter-component übereinstimmt. Im folgenden Beispiel ist der Namespace des Client -Projekts BlazorHosted.Client.

Fügen Sie in der Datei Program.cs des Client -Projekts den Namespace für die Razor-Komponenten des Projekts am Anfang der Datei hinzu:

using BlazorHosted.Client.Pages;

Nachdem das builder in Program.cs eingerichtet wurde, fügen Sie die Counter-Komponente als Stammkomponente hinzu:

builder.RootComponents.Add<Counter>("#counter-component");

Im folgenden Razor Pages-Beispiel wird die Komponente Counter auf einer Seite gerendert. Um die Komponente interaktiv zu gestalten, ist das Blazor WebAssembly-Skript im Renderabschnitt der Seite enthalten.

Im Server -Projekt, Pages/RazorPagesCounter2.cshtml:

@page

<div id="counter-component">Loading...</div>

@section Scripts {
    <script src="_framework/blazor.webassembly.js"></script>
}

Führen Sie das Server -Projekt aus. Navigieren Sie zur Razor-Seite unter /razorpagescounter2. Die vorab gerenderte Counter-Komponente ist in die Seite eingebettet.

Je nachdem, welche statischen Ressourcen die Komponenten verwenden und wie die Layoutseiten in einer App organisiert sind, können zusätzliche Arbeitsschritte erforderlich sein. Normalerweise werden Skripts zum Scripts-Renderabschnitt einer Seite oder Ansicht und Stylesheets zum <head>-Elementinhalt des Layouts hinzugefügt.

Hinweis

Das vorangehende Beispiel löst eine JSException aus, wenn eine Blazor WebAssembly-App vorab gerendert und in eine Razor Pages- oder MVC-App gleichzeitig mit einem CSS-Selektor eingebunden wird. Wenn Sie zu einer der Razor-Komponenten des Projekts Client navigieren oder zu einer Seite oder Ansicht des Projekts Server mit einer eingebetteten Komponente, wird mindestens eine JSException ausgelöst.

Dies ist normales Verhalten, da das Vorabrendern und die Integration einer Blazor WebAssembly-App mit routbaren Razor-Komponenten nicht mit der Verwendung von CSS-Selektoren kompatibel ist.

Wenn Sie mit den Beispielen in den vorherigen Abschnitten arbeiten und nur möchten, dass der CSS-Selektor in Ihrer Beispiel-App funktioniert, kommentieren Sie die Spezifikation der Stammkomponente App der Program.cs-Datei des Projekts Client aus:

- builder.RootComponents.Add<App>("#app");
+ //builder.RootComponents.Add<App>("#app");

Navigieren Sie zur Seite oder Ansicht mit der eingebetteten Komponente Razor, die einen CSS-Selektor verwendet (z. B. /razorpagescounter2 im vorherigen Beispiel). Die Seite oder Ansicht wird mit der eingebetteten Komponente geladen, und die eingebettete Komponente funktioniert wie erwartet.

Razor-Komponenten können in Razor Pages- und MVC-Apps integriert werden. Wenn die Seite oder Ansicht gerendert wird, können Komponenten gleichzeitig vorab gerendert werden.

Prerendering kann die Suchmaschinenoptimierung (Search Engine Optimization, SEO) verbessern, indem Inhalte für die erste HTTP-Antwort gerendert werden, die Suchmaschinen zum Berechnen des Seitenrangs verwenden können.

Verwenden Sie nach der Konfiguration des Projekts die Anleitungen in den folgenden Abschnitten abhängig von den Anforderungen des Projekts:

• Die folgenden Abschnitte beziehen sich auf Komponenten, die über Benutzeranforderungen direkt routingfähig sind. Befolgen Sie diese Anleitung, wenn Besucher in der Lage sein sollen, in ihrem Browser eine HTTP-Anforderung für eine Komponente mit einer @page-Direktive zu erstellen.
  • Verwenden routingfähiger Komponenten in einer Razor Pages-App
  • Verwenden routingfähiger Komponenten in einer MVC-App
• Informationen zu Komponenten, die über Benutzeranforderungen nicht direkt routingfähig sind, finden Sie im Abschnitt Rendern von Komponenten aus einer Seite oder Ansicht. Befolgen Sie diese Anleitung, wenn die App Komponenten mit dem Taghilfsprogramm für Komponenten in vorhandene Seiten und Ansichten einbettet.

Konfiguration

Verwenden Sie die folgende Anleitung, um Razor-Komponenten in Seiten und Ansichten einer vorhandenen Razor Pages- oder MVC-App zu integrieren.

1. Fügen Sie dem Ordner „root“ eine imports-Datei mit dem folgenden Inhalt hinzu. Ändern Sie den Platzhalter {APP NAMESPACE} in den Namespace des Projekts.

   _Imports.razor:

   @using System.Net.Http
   @using Microsoft.AspNetCore.Authorization
   @using Microsoft.AspNetCore.Components.Authorization
   @using Microsoft.AspNetCore.Components.Forms
   @using Microsoft.AspNetCore.Components.Routing
   @using Microsoft.AspNetCore.Components.Web
   @using Microsoft.AspNetCore.Components.Web.Virtualization
   @using Microsoft.JSInterop
   @using {APP NAMESPACE}
   

2. In der Layoutdatei des Projekts (Pages/Shared/_Layout.cshtml in Razor Pages-Apps oder Views/Shared/_Layout.cshtml in MVC-Apps):

   • Fügen Sie dem Element <head> das folgende <base>-Tag und das folgende Taghilfsprogramm für HeadOutlet-Komponenten hinzu:

     <base href="~/" />
     <component type="typeof(Microsoft.AspNetCore.Components.Web.HeadOutlet)" 
         render-mode="ServerPrerendered" />
     

     Der href-Wert (der App-Basispfad) im obigen Beispiel setzt voraus, dass die App sich im URL-Stammpfad (/) befindet. Wenn es sich bei der App um eine untergeordnete Anwendung handelt, befolgen Sie die Anweisungen im Abschnitt App-Basispfad des Artikels Hosten und Bereitstellen von Blazor in ASP.NET Core.

     Die HeadOutlet-Komponente wird verwendet, um den Kopfteilinhalt (<head>) für Seitentitel (PageTitle-Komponente) und andere Kopfteilelemente (HeadContent-Komponente) zu rendern, die durch Razor-Komponenten festgelegt werden. Weitere Informationen finden Sie unter Steuern des Inhalts von „head“ in Blazor-Apps in ASP.NET Core.

   • Fügen Sie ein <script>-Tag für das Skript blazor.server.js unmittelbar vor dem Renderabschnitt Scripts (@await RenderSectionAsync(...)) hinzu:

     <script src="_framework/blazor.server.js"></script>
     

     Das Framework fügt das Skript blazor.server.js zur App hinzu. Die Skriptdatei blazor.server.js muss nicht manuell zur App hinzugefügt werden.

   Hinweis

   In der Regel wird das Layout über die Datei _ViewStart.cshtml geladen.

3. Registrieren Sie die Blazor Server-Dienste in Program.cs, wo die Dienste registriert sind:

   builder.Services.AddServerSideBlazor();
   

4. Fügen Sie den Blazor-Hubendpunkt den Endpunkten von Program.cs hinzu, wo Routen zugeordnet sind. Platzieren Sie die folgende Zeile nach dem Aufruf von MapRazorPages (Razor Pages) oder MapControllerRoute (MVC):

   app.MapBlazorHub();
   

5. Integrieren Sie Komponenten in eine beliebige Seite oder Ansicht. Fügen Sie z. B. dem Ordner Shared des Projekts eine Counter-Komponente hinzu.

   Pages/Shared/Counter.razor (Razor Pages) oder Views/Shared/Counter.razor (MVC):

   <h1>Counter</h1>
   
   <p>Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

   Razor Pages:

   Fügen Sie auf der Index-Seite des Projekts einer Razor Pages-App den Namespace der Counter-Komponente hinzu, und betten Sie die Komponente in die Seite ein. Wenn die Index-Seite geladen wird, wird die Counter-Komponente auf der Seite vorab gerendert. Ersetzen Sie im folgenden Beispiel den Platzhalter {APP NAMESPACE} durch den Namespace des Projekts.

   Pages/Index.cshtml:

   @page
   @using {APP NAMESPACE}.Pages.Shared
   @model IndexModel
   @{
       ViewData["Title"] = "Home page";
   }
   
   <component type="typeof(Counter)" render-mode="ServerPrerendered" />
   

   MVC:

   Fügen Sie in der Index-Ansicht des Projekts einer MVC-App den Namespace der Counter-Komponente hinzu, und betten Sie die Komponente in die Ansicht ein. Wenn die Index-Ansicht geladen wird, wird die Counter-Komponente auf der Seite vorab gerendert. Ersetzen Sie im folgenden Beispiel den Platzhalter {APP NAMESPACE} durch den Namespace des Projekts.

   Views/Home/Index.cshtml:

   @using {APP NAMESPACE}.Views.Shared
   @{
       ViewData["Title"] = "Home Page";
   }
   
   <component type="typeof(Counter)" render-mode="ServerPrerendered" />
   

Weitere Informationen finden Sie im Abschnitt Rendern von Komponenten einer Seite oder Ansicht.

Verwenden routingfähiger Komponenten in einer Razor Pages-App

In diesem Abschnitt wird das Hinzufügen von Komponenten behandelt, die über Benutzeranforderungen direkt routingfähig sind.

So richten Sie die Unterstützung von routingfähigen Razor-Komponenten in Razor Pages-Apps ein:

1. Befolgen Sie die Anweisungen im Abschnitt Configuration.

2. Fügen Sie eine App-Komponente mit dem folgenden Inhalt zum Projektstamm hinzu.

   App.razor:

   @using Microsoft.AspNetCore.Components.Routing
   
   <Router AppAssembly="typeof(App).Assembly">
       <Found Context="routeData">
           <RouteView RouteData="routeData" />
       </Found>
       <NotFound>
           <PageTitle>Not found</PageTitle>
           <p role="alert">Sorry, there's nothing at this address.</p>
       </NotFound>
   </Router>
   

3. Fügen Sie dem Projekt eine _Host-Seite mit dem folgenden Inhalt hinzu. Ersetzen Sie den Platzhalter {APP NAMESPACE} durch den Namespace der App.

   Pages/_Host.cshtml:

   @page
   @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
   
   <component type="typeof(App)" render-mode="ServerPrerendered" />
   

   Hinweis

   Das vorherige Beispiel geht davon aus, dass die Komponente HeadOutlet und das Skript Blazor (_framework/blazor.server.js) vom Layout der App gerendert werden. Weitere Informationen finden Sie im Abschnitt Konfiguration.

   RenderMode konfiguriert folgende Einstellungen für die App-Komponente:

   • Ob die Komponente zuvor für die Seite gerendert wird
   • Ob die Komponente als statische HTML auf der Seite gerendert wird oder ob sie die nötigen Informationen für das Bootstrapping einer Blazor-App über den Benutzer-Agent enthält.

   Weitere Informationen zum Hilfsprogramm für Komponententags, einschließlich Übergabe von Parametern und Konfiguration von RenderMode, finden Sie unter Taghilfsprogramm für Komponenten in ASP.NET Core.

4. Fügen Sie in den Program.cs-Endpunkten eine Route mit niedriger Priorität für die _Host-Seite als letzten Endpunkt hinzu:

   app.MapFallbackToPage("/_Host");
   

5. Fügen Sie dem Projekt routingfähige Komponenten hinzu. Das folgende Beispiel ist eine RoutableCounter-Komponente, die auf der Counter-Komponente in den Blazor-Projektvorlagen basiert.

   Pages/RoutableCounter.razor:

   @page "/routable-counter"
   
   <PageTitle>Routable Counter</PageTitle>
   
   <h1>Routable Counter</h1>
   
   <p>Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

6. Führen Sie das Projekt aus, und navigieren Sie zu der routingfähigen RoutableCounter-Komponente unter /routable-counter.

Weitere Informationen zu Namespaces finden Sie im Abschnitt Komponentennamespaces.

Verwenden routingfähiger Komponenten in einer MVC-App

In diesem Abschnitt wird das Hinzufügen von Komponenten behandelt, die über Benutzeranforderungen direkt routingfähig sind.

So richten Sie die Unterstützung von routingfähigen Razor-Komponenten in MVC-Apps ein:

1. Befolgen Sie die Anweisungen im Abschnitt Configuration.

2. Fügen Sie eine App-Komponente mit dem folgenden Inhalt zum Projektstamm hinzu.

   App.razor:

   @using Microsoft.AspNetCore.Components.Routing
   
   <Router AppAssembly="typeof(App).Assembly">
       <Found Context="routeData">
           <RouteView RouteData="routeData" />
       </Found>
       <NotFound>
           <PageTitle>Not found</PageTitle>
           <p role="alert">Sorry, there's nothing at this address.</p>
       </NotFound>
   </Router>
   

3. Fügen Sie dem Projekt eine _Host-Ansicht mit dem folgenden Inhalt hinzu. Ersetzen Sie den Platzhalter {APP NAMESPACE} durch den Namespace der App.

   Views/Home/_Host.cshtml:

   @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
   
   <component type="typeof(App)" render-mode="ServerPrerendered" />
   

   Hinweis

   Das vorherige Beispiel geht davon aus, dass die Komponente HeadOutlet und das Skript Blazor (_framework/blazor.server.js) vom Layout der App gerendert werden. Weitere Informationen finden Sie im Abschnitt Konfiguration.

   RenderMode konfiguriert folgende Einstellungen für die App-Komponente:

   • Ob die Komponente zuvor für die Seite gerendert wird
   • Ob die Komponente als statische HTML auf der Seite gerendert wird oder ob sie die nötigen Informationen für das Bootstrapping einer Blazor-App über den Benutzer-Agent enthält.

   Weitere Informationen zum Hilfsprogramm für Komponententags, einschließlich Übergabe von Parametern und Konfiguration von RenderMode, finden Sie unter Taghilfsprogramm für Komponenten in ASP.NET Core.

4. Fügen Sie eine Aktion zum Home-Controller hinzu.

   Controllers/HomeController.cs:

   public IActionResult Blazor()
   {
      return View("_Host");
   }
   

5. Fügen Sie in den Program.cs-Endpunkten eine Route mit niedriger Priorität für die Controlleraktion hinzu, die die _Host-Ansicht zurückgibt:

   app.MapFallbackToController("Blazor", "Home");
   

6. Erstellen Sie einen Pages-Ordner in der MVC-App, und fügen Sie routingfähige Komponenten hinzu. Das folgende Beispiel ist eine RoutableCounter-Komponente, die auf der Counter-Komponente in den Blazor-Projektvorlagen basiert.

   Pages/RoutableCounter.razor:

   @page "/routable-counter"
   
   <PageTitle>Routable Counter</PageTitle>
   
   <h1>Routable Counter</h1>
   
   <p>Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

7. Führen Sie das Projekt aus, und navigieren Sie zu der routingfähigen RoutableCounter-Komponente unter /routable-counter.

Weitere Informationen zu Namespaces finden Sie im Abschnitt Komponentennamespaces.

Rendern von Komponenten einer Seite oder Ansicht

In diesem Abschnitt wird das Hinzufügen von Komponenten zu Seiten oder Ansichten behandelt, wenn die Komponenten nicht direkt über Benutzeranforderungen routingfähig sind.

Verwenden Sie das Komponententaghilfsprogramm zum Rendern einer Komponente einer Seite oder Ansicht.

Rendern zustandsbehafteter interaktiver Komponenten

Zustandsbehaftete interaktive Komponenten können einer Razor-Seite oder -Ansicht hinzugefügt werden.

Wenn die Seite oder Ansicht gerendert wird:

• Die Komponente wird mit der Seite oder Ansicht vorab gerendert.
• Der anfängliche Komponentenzustand, der zum Rendern vorab genutzt wurde, geht verloren.
• Der neue Komponentenzustand wird erstellt, wenn die SignalR-Verbindung hergestellt wird.

Die folgende Razor-Seite rendert eine Counter-Komponente:

<h1>Razor Page</h1>

<component type="typeof(Counter)" render-mode="ServerPrerendered" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Weitere Informationen finden Sie unter Taghilfsprogramm für Komponenten in ASP.NET Core.

Rendern nicht interaktiver Komponenten

Auf der folgenden Razor-Seite wird die Counter-Komponente statisch mit einem Anfangswert gerendert, der mit einem Formular angegeben wird. Da die Komponente statisch gerendert wird, ist die Komponente nicht interaktiv:

<h1>Razor Page</h1>

<form>
    <input type="number" asp-for="InitialValue" />
    <button type="submit">Set initial value</button>
</form>

<component type="typeof(Counter)" render-mode="Static" 
    param-InitialValue="InitialValue" />

@functions {
    [BindProperty(SupportsGet=true)]
    public int InitialValue { get; set; }
}

Weitere Informationen finden Sie unter Taghilfsprogramm für Komponenten in ASP.NET Core.

Komponentennamespaces

Wenn Sie einen benutzerdefinierten Ordner für die Razor-Komponenten des Projekts verwenden, fügen Sie den Namespace des Ordners zur Seite/Ansicht oder zur Datei _ViewImports.cshtml hinzu. Siehe folgendes Beispiel:

• Komponenten werden im Ordner Components des Projekts gespeichert.
• Der Platzhalter {APP NAMESPACE} steht für den Namespace des Projekts. Components stellt den Namen des Ordners dar.

@using {APP NAMESPACE}.Components

Die Datei _ViewImports.cshtml befindet sich im Ordner Pages einer Razor-Pages-App oder im Ordner Views einer MVC-App.

Weitere Informationen finden Sie unter Razor-Komponenten in ASP.NET Core.

Beibehalten des vorab gerenderten Zustands

Ohne Beibehaltung des vorab gerenderten Zustands geht der Zustand verloren, der während des Vorabrenderings verwendet wird, und muss neu erstellt werden, wenn die App vollständig geladen ist. Wenn ein Zustand asynchron eingerichtet wird, kann die Benutzeroberfläche flimmern, wenn die vorab gerenderte Benutzeroberfläche durch temporäre Platzhalter ersetzt und dann nochmals vollständig gerendert wird.

Um den Zustand für vorab gerenderte Komponenten beizubehalten, verwenden Sie das Hilfsprogramm „Persist Component State Tag“ (Referenzquelle). Fügen Sie das Hilfsprogramm-Tag <persist-component-state /> innerhalb des schließenden </body>-Tags der Seite _Host in einer App hinzu, die Komponenten vorab rendert.

Hinweis

Dokumentationslinks zur .NET-Referenzquelle laden in der Regel den Standardbranch des Repositorys, der die aktuelle Entwicklung für das nächste Release von .NET darstellt. Um ein Tag für ein bestimmtes Release auszuwählen, wählen Sie diesen mit der Dropdownliste Switch branches or tags (Branches oder Tags wechseln) aus. Weitere Informationen finden Sie unter How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Auswählen eines Versionstags von ASP.NET Core-Quellcode (dotnet/AspNetCore.Docs #26205)).

In Pages/_Host.cshtml von Blazor Anwendungen, die entweder in einer gehosteten Blazor WebAssembly-Anwendung mit WebAssembly vorgerendert sind (WebAssemblyPrerendered) oder in einer Blazor Server-Anwendung mit ServerPrerendered:

<body>
    ...

    <persist-component-state />
</body>

Entscheiden Sie, welcher Zustand mithilfe des Diensts PersistentComponentState beibehalten werden soll. Mit PersistentComponentState.RegisterOnPersisting wird zum Beibehalten des Komponentenzustands ein Rückruf registriert, bevor die App angehalten wird. Der Zustand wird abgerufen, wenn die Anwendung fortgesetzt wird.

Im folgenden Beispiel:

• Der Platzhalter {TYPE} stellt den Typ der zu speichernden Daten dar (z. B. WeatherForecast[]).
• Der Platzhalter {TOKEN} ist eine Zustandsbezeichnerzeichenfolge (z. B. fetchdata).

@implements IDisposable
@inject PersistentComponentState ApplicationState

...

@code {
    private {TYPE} data;
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistData);

        if (!ApplicationState.TryTakeFromJson<{TYPE}>(
            "{TOKEN}", out var restored))
        {
            data = await ...;
        }
        else
        {
            data = restored!;
        }
    }

    private Task PersistData()
    {
        ApplicationState.PersistAsJson("{TOKEN}", data);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose()
    {
        persistingSubscription.Dispose();
    }
}

Beim folgenden Beispiel handelt es sich um eine aktualisierte Version der FetchData-Komponente in einer gehosteten Blazor WebAssembly-App, die auf der Blazor-Projektvorlage basiert. Durch die Komponente WeatherForecastPreserveState wird Zustand der Wettervorhersage beim Vorabrendering beibehalten und anschließend zum Initialisieren der Komponente abgerufen. Mit dem Hilfsprogramm zum Beibehalten eines Komponentenzustandstags wird der Komponentenzustand nach allen Komponentenaufrufen dauerhaft gespeichert.

Pages/WeatherForecastPreserveState.razor:

@page "/weather-forecast-preserve-state"
@using BlazorSample.Shared
@implements IDisposable
@inject IWeatherForecastService WeatherForecastService
@inject PersistentComponentState ApplicationState

<PageTitle>Weather Forecast</PageTitle>

<h1>Weather forecast</h1>

<p>This component demonstrates fetching data from the server.</p>

@if (forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>Date</th>
                <th>Temp. (C)</th>
                <th>Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var forecast in forecasts)
            {
                <tr>
                    <td>@forecast.Date.ToShortDateString()</td>
                    <td>@forecast.TemperatureC</td>
                    <td>@forecast.TemperatureF</td>
                    <td>@forecast.Summary</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    private WeatherForecast[] forecasts = Array.Empty<WeatherForecast>();
    private PersistingComponentStateSubscription persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        persistingSubscription = 
            ApplicationState.RegisterOnPersisting(PersistForecasts);

        if (!ApplicationState.TryTakeFromJson<WeatherForecast[]>(
            "fetchdata", out var restored))
        {
            forecasts = 
                await WeatherForecastService.GetForecastAsync(DateOnly.FromDateTime(DateTime.Now));
        }
        else
        {
            forecasts = restored!;
        }
    }

    private Task PersistForecasts()
    {
        ApplicationState.PersistAsJson("fetchdata", forecasts);

        return Task.CompletedTask;
    }

    void IDisposable.Dispose()
    {
        persistingSubscription.Dispose();
    }
}

Durch das Initialisieren von Komponenten mit demselben Zustand, der während des Prerenderings verwendet wird, werden teure Initialisierungsschritte nur einmal ausgeführt. Die gerenderte Benutzeroberfläche entspricht auch der vorab gerenderten Benutzeroberfläche, sodass im Browser kein Flimmern auftritt.

Der beibehaltene vorrenderte Zustand wird an den Client übertragen, in dem er zum Wiederherstellen des Komponentenzustands verwendet wird. ASP.NET Kerndatenschutz stellt sicher, dass die Daten in Blazor Server Apps sicher übertragen werden. Für die Vorabenderung in einer gehosteten Blazor WebAssembly App werden die Daten für den Browser verfügbar gemacht und dürfen keine vertraulichen, privaten Informationen enthalten.

Zusätzliche Blazor WebAssembly-Ressourcen

• Zustandsverwaltung: Behandeln von Vorabrendern
• Unterstützung für Vorabrendern für Lazy Loading von Assemblys
• Razor-Lebenszyklusthemen, die sich auf Vorabrendern beziehen
  • Komponenteninitialisierung (OnInitialized{Async})
  • Nach dem Rendern der Komponente (OnAfterRender{Async})
  • Zustandsbehaftete erneute Verbindung nach dem Prerendering: Obwohl sich der Inhalt dieses Abschnitts auf Blazor Server und zustandsbehaftete erneute SignalR-Verbindung konzentriert, umfasst das Szenario für Prerendering in gehosteten Blazor WebAssembly-Apps (WebAssemblyPrerendered) ähnliche Bedingungen und Verfahren, um die doppelte Ausführung von Entwicklercode zu verhindern. Informationen zum Beibehalten des Zustands während der Ausführung des Initialisierungscodes während der Vorrenderung finden Sie im Abschnitt Beibehalten des vorgerenderten Zustands dieses Artikels.
  • Voarabrendering mit JavaScript-Interop
• Authentifizierungs- und Autorisierungsthemen, die sich auf Vorabrendern beziehen
  • Allgemeine Aspekte
  • Vorabrendering mit Authentifizierung in gehosteten Blazor WebAssembly-Apps
• Hosten und Bereitstellen: Blazor WebAssembly
• Behandeln von Fehlern: Prerendering
• OnNavigateAsync wird beim Prerendering zweimal ausgeführt: Behandeln von asynchronen Navigationsereignissen mit OnNavigateAsync

Vorab gerenderte Zustandsgröße und SignalR-Grenzwert für die Nachrichtengröße

Eine große vorab gerenderte Zustandsgröße kann den Grenzwert für die Nachrichtengröße der SignalR-Verbindung überschreiten, was Folgendes zur Folge hat:

• Die SignalR-Verbindung wird mit einem Fehler auf dem Client nicht initialisiert: Circuit host not initialized.
• Die Benutzeroberfläche für eine erneute Verbindung auf dem Client wird angezeigt, wenn die Verbindung fehlschlägt. Eine Wiederherstellung ist nicht möglich.

Verwenden Sie einen der folgenden Ansätze, um das Problem zu beheben:

• Verringern Sie die Menge der Daten, die Sie in den vorab gerenderten Zustand versetzen.
• Erhöhen Sie den SignalR-Grenzwert für die Nachrichtengröße. WARNUNG: Das Erhöhen des Grenzwerts kann das Risiko von Denial-of-Service-Angriffen (DoS) erhöhen.

Zusätzliche Blazor Server-Ressourcen

• Zustandsverwaltung: Behandeln von Vorabrendern
• Razor-Lebenszyklusthemen, die sich auf Vorabrendern beziehen
  • Komponenteninitialisierung (OnInitialized{Async})
  • Nach dem Rendern der Komponente (OnAfterRender{Async})
  • Zustandsbehaftete erneute Verbindung nach dem Prerendering
  • Voarabrendering mit JavaScript-Interop
• Authentifizierung und Autorisierung: Allgemeine Aspekte
• Behandeln von Fehlern: Prerendering
• Hosten und Bereitstellen: Blazor Server
• Bedrohungsminderung: Cross-Site Scripting (XSS)
• OnNavigateAsync wird beim Prerendering zweimal ausgeführt: Behandeln von asynchronen Navigationsereignissen mit OnNavigateAsync