ASP.NET Core Blazor Routing

In diesem Artikel wird das Blazor App-Anforderungsrouting mit Anleitungen zu statischem und interaktivem Routing, ASP.NET Core Endpoint Routing Integration, Navigationsereignissen und Routenvorlagen und Einschränkungen für Razor Komponenten erläutert.

Das Routing in Blazor erfolgt, indem mit einer @page-Anweisung eine Routenvorlage für jede zugängliche Komponente in der App bereitgestellt wird. Wenn eine Razor-Datei mit einer @page-Anweisung kompiliert wird, erhält die generierte Klasse ein RouteAttribute, das die Routenvorlage angibt. Zur Laufzeit sucht der Router nach Komponentenklassen mit einem RouteAttribute und rendert die Komponente, deren Routenvorlage mit der angeforderten URL übereinstimmt.

Die folgende HelloWorld-Komponente verwendet eine Routenvorlage /hello-world, und die gerenderte Webseite für die Komponente ist an der relativen URL /hello-world erreichbar.

HelloWorld.razor:

@page "/hello-world"

<h1>Hello World!</h1>

Die vorangehende Komponente wird im Browser am Punkt /hello-world geladen, unabhängig davon, ob Sie die Komponente als Link zur UI-Navigation der App hinzufügen oder nicht.

Statisches und interaktives Routing

Dieser Abschnitt gilt für Blazor Web Apps.

Wenn das Prerendering aktiviert ist, führt der Blazor-Router (Router-Komponente, <Router> in Routes.razor) während des statischen serverseitigen Renderings (statisches SSR) ein statisches Routing zu Komponenten durch. Dieser Routingtyp wird als statisches Routing bezeichnet.

Wenn der Routes-Komponente ein interaktiver Rendermodus zugewiesen wird, wird der Blazor-Router nach statischem SSR mit statischem Routing auf dem Server interaktiv. Diese Art von Routing wird als interaktives Routing bezeichnet.

Statische Router verwenden Endpunktrouting und den HTTP-Anforderungspfad, um zu bestimmen, welche Komponente gerendert werden soll. Wenn der Router interaktiv wird, wird die URL des Dokuments (die URL in der Adressleiste des Browsers) verwendet, um zu bestimmen, welche Komponente gerendert werden soll. Das bedeutet, dass der interaktive Router dynamisch ändern kann, welche Komponente gerendert wird, wenn sich die URL des Dokuments dynamisch in eine andere gültige interne URL ändert. Dazu ist keine HTTP-Anforderung zum Abrufen neuer Seiteninhalte erforderlich.

Interaktives Routing verhindert auch das Vorabrendern, da neue Seiteninhalte nicht vom Server über eine normale Seitenanforderung angefordert werden. Weitere Informationen finden Sie unter ASP.NET Core Blazor vorgerenderte Zustandspersistenz.

Integration von ASP.NET Core-Endpunktrouting

Dieser Abschnitt gilt für Blazor Web Apps, die über eine Leitung betrieben werden.

Blazor Web App wird in ASP.NET Core-Endpunktrouting integriert. Eine ASP.NET Core-App ist mit Endpunkten für routingfähige Komponenten und die Stammkomponente konfiguriert, die für diese Endpunkte in MapRazorComponents der Program Datei gerendert werden soll. Die Standardstammkomponente (erste geladene Komponente) ist die App-Komponente (App.razor):

app.MapRazorComponents<App>();

Routenvorlagen

Die Router-Komponente ermöglicht das Routing an Razor-Komponenten und befindet sich in der Routes-Komponente der App (Components/Routes.razor).

Wenn eine Razor-Komponente (.razor) mit einer @page-Anweisung kompiliert wird, wird für die generierte Komponentenklasse ein RouteAttribute-Objekt bereitgestellt, das die Routenvorlage der Komponente angibt.

Wenn die App gestartet wird, wird die Assembly gescannt, die als AppAssembly-Objekt des Routers angegeben wurde, um Routeninformationen für die Komponenten der App zu erfassen, die über ein RouteAttribute-Objekt verfügen.

Zur Laufzeit führt die RouteView-Komponente Folgendes aus:

• Sie empfängt das RouteData vom Router zusammen mit allen Routenparametern.
• Sie rendert die angegebene Komponente mit deren Layout, einschließlich aller weiteren geschachtelten Layouts.

Optional können Sie einen DefaultLayout-Parameter mit einer Layoutklasse für Komponenten angeben, die kein Layout mit der @layout-Anweisung festlegen. Die Blazor-Projektvorlagen des Frameworks geben die MainLayout-Komponente (MainLayout.razor) als Standardlayout der App an. Weitere Informationen zu Layouts finden Sie unter Blazor-Layouts in ASP.NET Core.

Komponenten unterstützen mehrere Routenvorlagen mithilfe mehrerer @page-Anweisungen. Die folgende Beispielkomponente wird bei Anfragen an /blazor-route und /different-blazor-route geladen.

BlazorRoute.razor:

@page "/blazor-route"
@page "/different-blazor-route"

<h1>Routing Example</h1>

<p>
    This page is reached at either <code>/blazor-route</code> or 
    <code>/different-blazor-route</code>.
</p>

Wichtig

Damit URLs ordnungsgemäß aufgelöst werden können, muss die App das Tag <base> (Speicherort des <head>-Inhalts) mit dem im Attribut href angegebenen App-Basispfad enthalten. Weitere Informationen finden Sie unter ASP.NET Core-App-BasispfadBlazor.

Alternativ zur Angabe der Routenvorlage als Zeichenfolgenliteral mit der Anweisung @page können konstantenbasierte Routenvorlagen mit der @attribute-Anweisung angegeben werden.

Im folgenden Beispiel wird die Anweisung @page in einer Komponente durch die Anweisung @attribute und die konstantenbasierte Routenvorlage in Constants.CounterRoute ersetzt, die an anderer Stelle in der App auf /counter festgelegt wird:

- @page "/counter"
+ @attribute [Route(Constants.CounterRoute)]

Fokussieren eines Elements bei der Navigation

Verwenden Sie die FocusOnNavigate-Komponente, um den UI-Fokus auf Grundlage eines CSS-Selektors auf ein Element festzulegen, nachdem Sie von einer Seite zu einer anderen navigiert sind.

<FocusOnNavigate RouteData="routeData" Selector="h1" />

Wenn die Router-Komponente zu einer neuen Seite navigiert, legt die FocusOnNavigate-Komponente den Fokus auf den Header der obersten Ebene (<h1>) der Seite fest. Dies ist eine gängige Strategie, um sicherzustellen, dass eine Seitennavigation bei Verwendung der Sprachausgabe angekündigt wird.

Bereitstellen von benutzerdefiniertem Inhalt, wenn kein Inhalt gefunden wurde

Für Anforderungen, bei denen Inhalt nicht gefunden wird, kann eine Razor Komponente dem Parameter der Router Komponente NotFoundPage zugewiesen werden. Der Parameter arbeitet in Abstimmung mit NavigationManager.NotFound, einer Methode, die im Entwicklercode aufgerufen wird, die eine "Nicht gefunden"-Antwort auslöst. NavigationManager.NotFoundwird im nächsten Artikel ASP.NET Core-Navigation Blazorbeschrieben.

Die Blazor Projektvorlage enthält eine NotFound.razor Seite. Diese Seite wird bei jedem NavigationManager.NotFound Aufruf automatisch gerendert, sodass fehlende Routen mit einer konsistenten Benutzeroberfläche verarbeitet werden können.

NotFound.razor:

@page "/not-found"
@layout MainLayout

<h3>Not Found</h3>
<p>Sorry, the content you are looking for does not exist.</p>

Die NotFound Komponente wird dem Parameter des Routers NotFoundPage zugewiesen. NotFoundPage unterstützt Routing, das für Statuscodeseiten für die erneute Ausführung von Middleware verwendet werden kann, einschließlich solcher, die ohneBlazor Middleware ausgeführt werden.

Im folgenden Beispiel ist die vorangehende NotFound Komponente im Ordner der App Pages vorhanden und an den NotFoundPage Parameter übergeben:

<Router AppAssembly="@typeof(Program).Assembly" NotFoundPage="typeof(Pages.NotFound)">
    <Found Context="routeData">
        <RouteView RouteData="@routeData" />
        <FocusOnNavigate RouteData="@routeData" Selector="h1" />
    </Found>
</Router>

Weitere Informationen finden Sie im nächsten Artikel zur ASP.NET Core-NavigationBlazor.

Weiterleiten an Komponenten aus mehreren Assemblys

Dieser Abschnitt gilt für Blazor Web Apps.

Verwenden Sie den Parameter Router der AdditionalAssemblies-Komponente und den Endpunktkonventions-Generator AddAdditionalAssemblies, um routingfähige Komponenten in zusätzlichen Assemblys zu ermitteln. In den folgenden Unterabschnitten wird erläutert, wann und wie die einzelnen APIs verwendet werden.

Statisches Routing

Um routbare Komponenten von zusätzlichen Assemblys für statisches serverseitiges Rendering (statisches SSR) zu ermitteln, auch wenn der Router später interaktiv für das Rendering wird, müssen die Assemblys dem Blazor-Framework bereitgestellt werden. Rufen Sie die AddAdditionalAssemblies-Methode mit den zusätzlichen Assemblys auf, die in der Datei MapRazorComponents des Serverprojekts mit Program verkettet sind.

Das folgende Beispiel enthält die routingfähigen Komponenten in der Assembly des BlazorSample.Client-Projekts. Dazu wird die Datei _Imports.razor des Projekts verwendet:

app.MapRazorComponents<App>()
    .AddAdditionalAssemblies(typeof(BlazorSample.Client._Imports).Assembly);

Hinweis

Die vorstehende Anleitung gilt auch für Szenarien mit Komponentenklassenbibliotheken. Weitere wichtige Anleitungen für Klassenbibliotheken und statisches SSR finden Sie in den ASP.NET Core Razor-Klassenbibliotheken (Razor Class Libraries, RCLs) mit statischem serverseitigem Rendering (statisches SSR).

Interaktives Routing

Der Routes-Komponente (Routes.razor) kann ein interaktiver Rendermodus zugewiesen werden. Dadurch wird der Blazor-Router nach statischem SSR und statischem Routing auf dem Server interaktiv. <Routes @rendermode="InteractiveServer" /> weist beispielsweise der Routes-Komponente interaktives serverseitiges Rendering (interaktives SSR) zu. Die Router-Komponente erbt interaktives serverseitiges Rendering (interaktives SSR) von der Routes-Komponente. Der Router wird nach dem statischen Routing auf dem Server interaktiv.

Die interne Navigation für interaktives Routing umfasst nicht das Anfordern neuer Seiteninhalte vom Server. Daher findet das Vorabrendern nicht für interne Seitenanforderungen statt. Weitere Informationen finden Sie unter ASP.NET Core Blazor vorgerenderte Zustandspersistenz.

Wenn die Routes-Komponente im Serverprojekt definiert ist, sollte der AdditionalAssemblies-Parameter der Router-Komponente die Assembly des .Client-Projekts enthalten. Dadurch kann der Router bei interaktivem Rendering ordnungsgemäß funktionieren.

Im folgenden Beispiel befindet sich die Routes-Komponente im Serverprojekt, und die Datei _Imports.razor des BlazorSample.Client-Projekts gibt die Assembly an, die nach routingfähigen Komponenten durchsucht werden soll:

<Router
    AppAssembly="..."
    AdditionalAssemblies="[ typeof(BlazorSample.Client._Imports).Assembly ]">
    ...
</Router>

Zusätzliche Assemblys werden neben der für AppAssembly angegebenen Assembly gescannt.

Hinweis

Die vorstehende Anleitung gilt auch für Szenarien mit Komponentenklassenbibliotheken.

Alternativ sind routingfähige Komponenten nur im .Client-Projekt vorhanden, wobei eine globale interaktive WebAssembly oder automatisches Rendering angewendet wird, und die Routes-Komponente wird im .Client-Projekt, nicht im Serverprojekt definiert. In diesem Fall gibt es keine externen Assemblys mit routingfähigen Komponenten, daher ist es nicht erforderlich, einen Wert für AdditionalAssemblies anzugeben.

Routenparameter

Der Router verwendet Routenparameter, um die entsprechenden Komponentenparameter mit demselben Namen aufzufüllen. Bei den Routenparameternamen muss die Groß- und Kleinschreibung nicht berücksichtigt werden. Im folgenden Beispiel weist der Parameter text den Wert des Routensegments der Eigenschaft Text der Komponente zu. Wenn eine Anforderung für /route-parameter-1/amazing erfolgt, wird der Inhalt als Blazor is amazing! gerendert.

RouteParameter1.razor:

@page "/route-parameter-1/{text}"

<h1>Route Parameter Example 1</h1>

<p>Blazor is @Text!</p>

@code {
    [Parameter]
    public string? Text { get; set; }
}

Optionale Parameter werden unterstützt. Im folgenden Beispiel weist der optionale Parameter text den Wert des Routensegments der Eigenschaft Text der Komponente zu. Wenn das Segment nicht vorhanden ist, wird der Wert von Text auf fantastic festgelegt.

RouteParameter2.razor:

@page "/route-parameter-2/{text?}"

<h1>Route Parameter Example 2</h1>

<p>Blazor is @Text!</p>

@code {
    [Parameter]
    public string? Text { get; set; }

    protected override void OnParametersSet() => Text = Text ?? "fantastic";
}

Wenn die OnInitialized{Async}-Lebenszyklusmethode anstelle der OnParametersSet{Async}-Lebenszyklusmethode verwendet wird, erfolgt die Standardzuweisung der Text-Eigenschaft zu fantastic nicht, wenn Benutzende innerhalb derselben Komponente navigieren. Diese Situation tritt z. B. auf, wenn von /route-parameter-2/amazing zu /route-parameter-2 navigiert wird. Da die Komponenteninstanz beibehalten wird und neue Parameter akzeptiert, wird die Methode OnInitialized nicht erneut aufgerufen.

Routeneinschränkungen

Eine Routeneinschränkung erzwingt die Typübereinstimmung in einem Routensegment zu einer Komponente.

Im folgenden Beispiel stimmt die Route zur User-Komponente nur überein, wenn:

• ein Id-Routensegment in der Anforderungs-URL vorhanden ist.
• das Id-Segment ein Integer (int) ist.

User.razor:

@page "/user/{Id:int}"

<h1>User Example</h1>

<p>User Id: @Id</p>

@code {
    [Parameter]
    public int Id { get; set; }
}

Die in der folgenden Tabelle aufgeführten Routeneinschränkungen sind verfügbar. Weitere Informationen zu den Routeneinschränkungen, die der invarianten Kultur entsprechen, finden Sie in der Hinweismeldung unterhalb der Tabelle.

Einschränkung	Beispiel	Beispielübereinstimmungen	Invariante Kultur Übereinstimmend
bool	{active:bool}	true, FALSE	Nein
datetime	{dob:datetime}	2016-12-31, 2016-12-31 7:32pm	Ja
decimal	{price:decimal}	49.99, -1,000.01	Ja
double	{weight:double}	1.234, -1,001.01e8	Ja
float	{weight:float}	1.234, -1,001.01e8	Ja
guid	{id:guid}	00001111-aaaa-2222-bbbb-3333cccc4444, {00001111-aaaa-2222-bbbb-3333cccc4444}	Nein
int	{id:int}	123456789, -123456789	Ja
long	{ticks:long}	123456789, -123456789	Ja
nonfile	{parameter:nonfile}	Nicht BlazorSample.styles.css, nicht favicon.ico	Ja

Warnung

Für Routeneinschränkungen, mit denen die URL überprüft wird und die in den CLR-Typ umgewandelt werden (beispielsweise int oder DateTime), wird immer die invariante Kultur verwendet. Diese Einschränkungen setzen voraus, dass die URL nicht lokalisierbar ist.

Routeneinschränkungen funktionieren auch mit optionalen Parametern. Im folgenden Beispiel ist Id erforderlich, während Option ein optionaler boolescher Routenparameter ist.

User.razor:

@page "/user/{id:int}/{option:bool?}"

<p>
    Id: @Id
</p>

<p>
    Option: @Option
</p>

@code {
    [Parameter]
    public int Id { get; set; }

    [Parameter]
    public bool Option { get; set; }
}

Vermeiden der Dateierfassung in einem Routenparameter

Die folgende Routenvorlage erfasst versehentlich statische Objektpfade in seinem optionalen Routenparameter (Optional). Zum Beispiel wird das Stylesheet der App (.styles.css) erfasst, wodurch die Stile der App zerstört werden:

@page "/{optional?}"

...

@code {
    [Parameter]
    public string? Optional { get; set; }
}

Um einen Routenparameter auf die Erfassung von Nicht-Dateipfaden zu beschränken, verwenden Sie die :nonfile-Einschränkung in der Routenvorlage:

@page "/{optional:nonfile?}"

Catch-All-Routenparameter

Catch-All-Routenparameter, die Pfade über mehrere Ordnergrenzen hinweg erfassen, werden in Komponenten unterstützt.

Für Catch-All-Routenparameter gilt:

• Sie müssen so benannt werden, dass sie dem Routensegmentnamen entsprechen. Die Groß-/Kleinschreibung muss bei der Benennung nicht beachtet werden.
• Ein string-Typ. Im Framework steht keine automatische Übertragung zur Verfügung.
• Am Ende der URL.

CatchAll.razor:

@page "/catch-all/{*pageRoute}"

<h1>Catch All Parameters Example</h1>

<p>Add some URI segments to the route and request the page again.</p>

<p>
    PageRoute: @PageRoute
</p>

@code {
    [Parameter]
    public string? PageRoute { get; set; }
}

Bei der URL /catch-all/this/is/a/test mit der Routenvorlage /catch-all/{*pageRoute} wird der Wert für PageRoute auf this/is/a/test festgelegt.

Schrägstriche und Segmente des erfassten Pfads werden decodiert. Bei einer Routenvorlage von /catch-all/{*pageRoute} ergibt die URL /catch-all/this/is/a%2Ftest%2A das Ergebnis this/is/a/test*.

Asynchrone Navigationsereignisse mit OnNavigateAsync behandeln

Die Router-Komponente unterstützt ein OnNavigateAsync-Feature. Der OnNavigateAsync-Handler wird aufgerufen, wenn der Benutzer:

• Der/die Nutzer besucht eine Strecke zum ersten Mal, indem er/sie direkt im Browser dorthin navigiert.
• Navigiert mithilfe eines Links oder eines NavigationManager.NavigateTo-Aufrufs zu einer neuen Route. Diese Methode wird im Entwicklercode aufgerufen, um zu einem URI zu navigieren. [NavigationManager API wird im nächsten Artikel ASP.NET Core-Navigation Blazorbeschrieben.]

<Router AppAssembly="typeof(App).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext args)
    {
        ...
    }
}

Ein Beispiel, in dem OnNavigateAsync verwendet wird, finden Sie unter Verzögertes Laden von Assemblys in Blazor WebAssembly in ASP.NET Core.

Beim Vorabrendering auf dem Server wird OnNavigateAsynczweimal ausgeführt:

• Einmal, wenn die angeforderte Endpunktkomponente zunächst statisch gerendert wird.
• Ein zweites Mal, wenn der Browser die Endpunktkomponente rendert.

Um zu verhindern, dass Entwicklercode in OnNavigateAsync doppelt ausgeführt wird, kann die Routes-Komponente NavigationContext zur Verwendung in der OnAfterRender{Async}-Lebenszyklusmethode speichern, wo firstRender überprüft werden kann. Weitere Informationen finden Sie unter Vorabrendern mit JavaScript-Interoperabilität.

Verarbeiten von Abbrüchen in OnNavigateAsync

Das NavigationContext-Objekt, das an den OnNavigateAsync-Rückruf übergeben wird, enthält ein CancellationToken, das beim Auftreten eines neuen Navigationsereignisses festgelegt wird. Der OnNavigateAsync-Rückruf muss ausgelöst werden, wenn dieses Abbruchtoken festgelegt wird, um zu vermeiden, dass der OnNavigateAsync-Rückruf für eine veraltete Navigation weiterhin ausgeführt wird.

Wenn ein Benutzer zu einem Endpunkt navigiert, aber dann sofort zu einem neuen Endpunkt wechselt, sollte die App den OnNavigateAsync-Rückruf für den ersten Endpunkt nicht weiter ausführen.

Siehe folgendes Beispiel:

• Das Abbruchtoken wird im Aufruf von PostAsJsonAsync übergeben, der den POST-Vorgang abbrechen kann, wenn der Benutzer vom /about-Endpunkt weg navigiert.
• Das Abbruchtoken wird während eines Produktvorabrufs festgelegt, wenn der Benutzer vom /store-Endpunkt weg navigiert.

@inject HttpClient Http
@inject ProductCatalog Products

<Router AppAssembly="typeof(App).Assembly" 
    OnNavigateAsync="OnNavigateAsync">
    ...
</Router>

@code {
    private async Task OnNavigateAsync(NavigationContext context)
    {
        if (context.Path == "/about") 
        {
            var stats = new Stats { Page = "/about" };
            await Http.PostAsJsonAsync("api/visited", stats, 
                context.CancellationToken);
        }
        else if (context.Path == "/store")
        {
            var productIds = new[] { 345, 789, 135, 689 };

            foreach (var productId in productIds) 
            {
                context.CancellationToken.ThrowIfCancellationRequested();
                Products.Prefetch(productId);
            }
        }
    }
}

Hinweis

Wenn der Rückruf nicht ausgelöst wird, wenn das Abbruchtoken in NavigationContext abgebrochen wird, kann dies zu unbeabsichtigtem Verhalten führen, z. B. zum Rendern einer Komponente aus einer vorherigen Navigation.

Benutzerinteraktion mit <Navigating>-Inhalt

Wenn während der Navigation eine erhebliche Verzögerung auftritt, z. B. bei Lazy-Loading-Assemblys in einer Blazor WebAssembly-App oder langsamer Netzwerkverbindung mit einer serverseitigen Blazor-App, kann die Router-Komponente dem oder der Benutzer*in mitteilen, dass ein Seitenübergang auftritt.

Fügen Sie oben in der Komponente, die die Router-Komponente angibt, eine @using-Anweisung für den Microsoft.AspNetCore.Components.Routing-Namespace hinzu:

@using Microsoft.AspNetCore.Components.Routing

Bereitstellen von Inhalten für den Navigating-Parameter für die Anzeige während Seitenübergangsereignissen.

Im Inhalt des Routerelements (<Router>...</Router>):

<Navigating>
    <p>Loading the requested page&hellip;</p>
</Navigating>

Ein Beispiel, in dem die Navigating-Eigenschaft verwendet wird, finden Sie unter Verzögertes Laden von Assemblys in Blazor WebAssembly in ASP.NET Core.