ASP.NET Core útvonalkezelés Blazor

Ez a cikk ismerteti az alkalmazáskérések útválasztását, Blazor a statikus és interaktív útválasztásról, az ASP.NET Core végpont-útválasztási integrációjáról, a navigációs eseményekről, valamint a Razor összetevők útvonalsablonjairól és korlátozásairól.

A Blazor útválasztása úgy érhető el, hogy egy útvonalsablont biztosít az alkalmazás minden akadálymentes összetevőjének egy @page irányelvvel. Ha egy Razor irányelvvel rendelkező @page-fájlt állít össze, a generált osztály kap egy RouteAttribute, amely megadja az útvonalsablont. Futásidőben az útválasztó keres egy RouteAttribute jelöléssel ellátott összetevőosztályokat, és megjeleníti azt az összetevőt, amelynek útvonalsablonja megfelel a kért URL-címnek.

Az alábbi HelloWorld összetevő /hello-worldútvonalsablont használ, és az összetevő renderelt weblapja a relatív URL-/hello-worldérhető el.

HelloWorld.razor:

@page "/hello-world"

<h1>Hello World!</h1>

Az előző összetevő attól függetlenül betöltődik a böngészőben /hello-world , hogy hozzáadja-e az összetevőt az alkalmazás felhasználói felületi navigációjához hivatkozásként.

Statikus és interaktív útválasztás

Ez a szakasz a Blazor Web Apps. szól.

Ha a előrenderelés engedélyezve van, a Blazor útválasztó (Router összetevő, <Router>Routes.razor) statikus útválasztást hajt végre az összetevőkhöz a statikus kiszolgálóoldali renderelés során (statikus SSR). Ezt az útválasztási típust statikus útválasztásnaknevezik.

Ha egy interaktív renderelési mód van hozzárendelve a Routes összetevőhöz, a Blazor útválasztó interaktívvá válik a statikus SSR után a kiszolgálón statikus útválasztással. Ezt az útválasztási típust interaktív útválasztásinevezik.

A statikus útválasztók végpont-útválasztással és HTTP-kérési útvonalsal határozzák meg, hogy melyik összetevőt kell megjeleníteni. Amikor az útválasztó interaktívvá válik, a dokumentum URL-címével (a böngésző címsorában található URL-címmel) határozza meg, hogy melyik összetevőt szeretné megjeleníteni. Ez azt jelenti, hogy az interaktív útválasztó dinamikusan módosíthatja, hogy melyik összetevő jelenik meg, ha a dokumentum URL-címe dinamikusan egy másik érvényes belső URL-címre változik, és ezt anélkül teheti meg, hogy HTTP-kérést hajt végre az új oldaltartalom beolvasásához.

Az interaktív útválasztás azért is megakadályozza az előrendelést, mert a rendszer nem kér új laptartalmat a kiszolgálótól normál lapkérelem esetén. További információ: ASP.NET Core Blazor előre beállított állapotmegőrzés.

ASP.NET core végpont útválasztási integrációja

Ez a szakasz a Blazor Web Appáramkörön működőkre vonatkozik.

A Blazor Web App be van építve a ASP.NET Core végpont-útválasztásirendszerébe. A ASP.NET Core-alkalmazás végpontokkal van konfigurálva az routable-összetevőkhöz és a gyökérösszetevőhöz, hogy megjelenítse az adott végpontokat MapRazorComponents a Program fájlban. Az alapértelmezett gyökérösszetevő (első betöltött összetevő) a App összetevő (App.razor):

app.MapRazorComponents<App>();

Útvonalsablonok

A Router összetevő lehetővé teszi Razor összetevők útválasztását, és az alkalmazás Routes összetevőjében (Components/Routes.razor) található.

Ha egy összetevőt (), amely egy irányelvvel rendelkezik, lefordítunk, a létrehozott összetevőosztály számára egy lesz biztosítva, amely az összetevő útvonalsablonját határozza meg.

Amikor az alkalmazás elindul, a Router AppAssembly-ként megadott szerelvényt átvizsgálják, hogy összegyűjtsék az útvonal információkat az alkalmazás azon összetevőihez, amelyek RouteAttribute-el rendelkeznek.

Futásidőben a RouteView komponens:

• A RouteData megkapja a Router-től az összes útvonalparaméterrel együtt.
• Rendereli a megadott összetevőt a elrendezésével, beleértve a további beágyazott elrendezéseket is.

Igény szerint megadhat egy DefaultLayout paramétert olyan összetevők elrendezési osztályával, amelyek nem a @layout irányelvelrendezését adják meg. A keretrendszer Blazor projektsablonjai az alkalmazás alapértelmezett elrendezéseként a MainLayout összetevőt (MainLayout.razor) adhatja meg. További információ az elrendezésekről: ASP.NET Core Blazor elrendezések.

Az összetevők több útvonalsablont támogatnak több @page direktívahasználatával. Az alábbi példaösszetevő betöltődik, amikor a /blazor-route és a /different-blazor-routekérések érkeznek.

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>

Fontos

Ahhoz, hogy az URL-címek megfelelően feloldódjanak, az alkalmazásnak tartalmaznia kell egy <base> címkét (<head> tartalom helyét) a href attribútumban megadott alkalmazásbázis-elérési úttal. További információ: ASP.NET Core-alkalmazás Blazor alap elérési útja.

Alternatívaként az útvonalsablon szövegként történő megadására az @page irányelvvel, konstansokra épülő útvonalsablonok is megadhatók az @attribute irányelvsegítségével.

Az alábbi példában egy összetevő @page irányelve helyébe a @attribute irányelv és a Constants.CounterRouteállandóalapú útvonalsablonja lép, amely az alkalmazás más részein a következőre van állítva: "/counter":

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

Navigáció közben egy elemre fókuszálj

A FocusOnNavigate összetevő egy CSS-választón alapuló elemre állítja a felhasználói felület fókuszát, miután egyik oldalról a másikra navigált.

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

Amikor a Router összetevő egy új lapra navigál, a FocusOnNavigate összetevő a lap felső szintű fejlécére (<h1>) helyezi a fókuszt. Ez egy gyakori stratégia annak biztosítására, hogy a képernyőolvasó használatakor az oldalnavigációt bejelentse.

Egyéni tartalom megadása, ha a tartalom nem található

Olyan kérések esetén, ahol a tartalom nem található, egy Razor összetevő rendelhető hozzá Router.NotFoundPage. A paraméter együttműködik a nem található választ aktiváló fejlesztői kódban meghívott metódussal NavigationManager.NotFound.

A Blazor projektsablon tartalmaz egy NotFound.razor lapot. Ez az oldal automatikusan megjelenítésre kerül minden alkalommal, amikor a NotFound hívásra kerül, így egységes felhasználói élménnyel kezelheti a hiányzó útvonalakat.

NotFound.razor:

@page "/not-found"
@layout MainLayout

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

A NotFound összetevő a router Router.NotFoundPage paraméteréhez van hozzárendelve, amely támogatja az útválasztást, amely az állapotkódlapok újbóli végrehajtását lehetővé tevő köztes szoftveren keresztül történhet, beleértve a nem köztes szoftvereket is.

Az alábbi példában az előző NotFound összetevő jelen van az alkalmazás mappájában Pages , és átadja a Router.NotFoundPage paraméternek:

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

További információt a ASP.NET Core Blazor navigációról szóló következő cikkben talál.

Útvonal több szerelvényből származó komponensekhez

Ez a szakasz a Blazor Web Apps. szól.

A Router összetevő AdditionalAssemblies paraméterének és a végpontkonvenció-szerkesztő AddAdditionalAssemblies-nek a segítségével felfedezheti a további szerelvényekben található útválasztható összetevőket. Az alábbi alszakaszok bemutatják, hogy mikor és hogyan kell használni az egyes API-kat.

Statikus útválasztás

A statikus kiszolgálóoldali rendereléshez (statikus SSR) szükséges további szerelvényekből származó útvonalasítható összetevők felfedezéséhez, még akkor is, ha a router később interaktívvá válik az interaktív rendereléshez, a szerelvényeket közzé kell tenni a Blazor keretrendszer számára. Hívja meg a AddAdditionalAssemblies metódust a kiszolgálóprojekt MapRazorComponents fájljában lévő, Program-hez összeláncolt további szerelvényekkel.

Az alábbi példa a BlazorSample.Client projekt szerelvényei közé tartozó routable összetevőket tartalmazza, a projekt _Imports.razor fájlját használva.

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

Jegyzet

Az előző útmutató összetevőosztály-kódtár forgatókönyvekre is vonatkozik. Az osztálykönyvtárakhoz és a statikus SSR-hez további fontos útmutatást talál az ASP.NET Core Razor osztálykönyvtárakban (RCLs), amelyek statikus kiszolgálóoldali rendereléssel.

Interaktív útválasztás

A Routes összetevőhöz (Routes.razor) interaktív renderelési mód rendelhető, amely lehetővé teszi, hogy a Blazor útválasztó interaktívvá váljon a statikus SSR és a statikus útválasztás után a kiszolgálón. Például <Routes @rendermode="InteractiveServer" /> az interaktív kiszolgálóoldali renderelést (interaktív SSR) rendeli hozzá a Routes összetevőhöz. A Router összetevő örökli az interaktív kiszolgálóoldali renderelést (interaktív SSR) a Routes összetevőtől. Az útválasztó interaktívvá válik a szerveren végzett statikus útválasztás után.

Az interaktív útválasztás belső navigációja nem foglalja magában az új laptartalom kérését a kiszolgálótól. Ezért a belső oldalkérések esetében nem történik meg az előrenderelés. További információ: ASP.NET Core Blazor előre beállított állapotmegőrzés.

Ha a Routes összetevő a kiszolgálóprojektben van definiálva, a AdditionalAssemblies összetevő Router paraméterének tartalmaznia kell a .Client projekt szerelvényét. Lehetővé teszi, hogy az útválasztó interaktív rendereléskor megfelelően működjön.

Az alábbi példában a Routes összetevő a kiszolgálóprojektben található, és a _Imports.razor projekt BlazorSample.Client fájlja jelzi az összeszerelést a továbbítható összetevők kereséséhez.

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

A rendszer a AppAssembly megadott szerelvényen kívül további szerelvényeket is beolvas.

Jegyzet

Az előző útmutató összetevőosztály-kódtár forgatókönyvekre is vonatkozik.

Alternatívaként, a csak a .Client projektben létező irányítható összetevők globális interaktív WebAssembly vagy automatikus rendereléssel kerülnek alkalmazásra, és a Routes összetevő a .Client projektben van meghatározva, nem a kiszolgáló projektben. Ebben az esetben nincsenek olyan külső szerelvények, amelyek kivehető összetevőkkel rendelkeznek, ezért nem szükséges megadni a AdditionalAssembliesértékét.

Útvonalparaméterek

Az útválasztó útvonalparaméterekkel tölti fel a megfelelő komponensparamétereket ugyanilyen névvel. Az útvonalparaméterek nevei nem érzékenyek a kis- és nagybetűkre. Az alábbi példában a text paraméter az útvonalszegmens értékét rendeli hozzá az összetevő Text tulajdonságához. Amikor egy kérés érkezik /route-parameter-1/amazing-ra, a tartalom Blazor is amazing!-ként jelenik meg.

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; }
}

A választható paraméterek támogatottak. Az alábbi példában a text választható paraméter az útvonalszegmens értékét rendeli hozzá az összetevő Text tulajdonságához. Amennyiben a szegmens nincs jelen, a Text értéke fantastic lesz.

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

Ha a OnInitialized{Async} életciklus-metódushelyett OnParametersSet{Async} életciklus-metódust használja, a Text tulajdonság alapértelmezett hozzárendelése nem történik meg fantastic, ha a felhasználó ugyanabban az összetevőben navigál. Ez a helyzet például akkor fordul elő, amikor a felhasználó /route-parameter-2/amazing-ről /route-parameter-2-re navigál. Mivel az összetevőpéldány továbbra is megmarad, és új paramétereket fogad el, a OnInitialized metódus nem lesz újra meghívva.

Útvonalkorlátozások

Az útvonalkorlátozás egy útvonalszegmens típusának megfelelő illesztését kényszeríti ki egy összetevőre.

A következő példában a User összetevőhöz vezető útvonal csak akkor egyezik meg, ha:

• A kérelem URL-címében Id útvonalszakasz található.
• A Id szegmens egész (int) típusú.

User.razor:

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

<h1>User Example</h1>

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

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

Az alábbi táblázatban látható útvonalkorlátozások elérhetők. Az invariáns kultúrának megfelelő útvonalkorlátozásokról további információt a táblázat alatti figyelmeztetésben talál.

Kényszer	Példa	Példa egyezések	Invariáns kulturális környezet összeillő
bool	{active:bool}	true, FALSE	Nem
datetime	{dob:datetime}	2016-12-31, 2016-12-31 7:32pm	Igen
decimal	{price:decimal}	49.99, -1,000.01	Igen
double	{weight:double}	1.234, -1,001.01e8	Igen
float	{weight:float}	1.234, -1,001.01e8	Igen
guid	{id:guid}	00001111-aaaa-2222-bbbb-3333cccc4444, {00001111-aaaa-2222-bbbb-3333cccc4444}	Nem
int	{id:int}	123456789, -123456789	Igen
long	{ticks:long}	123456789, -123456789	Igen
nonfile	{parameter:nonfile}	Nem BlazorSample.styles.css, nem favicon.ico	Igen

Figyelmeztetés

Az URL-címet ellenőrző és CLR-típussá (például int vagy DateTime) konvertált útvonalkorlátozások mindig az invariáns kultúrát használják. Ezek a korlátozások feltételezik, hogy az URL-cím nem honosítható.

Az útvonalkorlátozások választható paraméterekkel is működnek. Az alábbi példában Id szükséges, de Option egy nem kötelező logikai útvonalparaméter.

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; }
}

A fájlrögzítés elkerülése útvonalparaméterben

Az alábbi útvonalsablon véletlenül rögzíti a statikus objektum elérési útját az opcionális útvonalparaméterben (Optional). A rendszer például rögzíti az alkalmazás stíluslapját (.styles.css), amely megszakítja az alkalmazás stílusát:

@page "/{optional?}"

...

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

Ha egy útvonalparamétert fájlon kívüli útvonalak rögzítésére szeretne korlátozni, használja a :nonfile korlátozási az útvonalsablonban:

@page "/{optional:nonfile?}"

Mindenre kiterjedő útvonalparaméterek

Az összetevők támogatják az univerzális útvonalparamétereket, amelyek több mappahatáron keresztül rögzítik az útvonalakat.

A mindent lefedő útvonalparaméterek a következők:

• Az útvonalszegmens nevének megfelelő névvel elnevezve. A név nem érzékeny a kis- és nagybetűkre.
• string típus. A keretrendszer nem biztosít automatikus öntést.
• Az URL-cím végén.

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; }
}

A /catch-all/this/is/a/testútvonalsablont tartalmazó URL-/catch-all/{*pageRoute} esetén a PageRoute értéke this/is/a/test.

A rögzített elérési út perjeleit és szegmenseit dekódolják. A /catch-all/{*pageRoute}útvonalsablonja esetén a /catch-all/this/is/a%2Ftest%2A URL-cím this/is/a/test*eredményez.

Aszinkron navigációs események kezelése OnNavigateAsync

A Router összetevő támogatja a OnNavigateAsync funkciót. A OnNavigateAsync kezelő akkor lesz meghívva, ha a felhasználó:

• Első alkalommal látogat meg egy útvonalat úgy, hogy közvetlenül a böngészőben navigál hozzá.
• Egy új útvonalra lép egy hivatkozással vagy egy NavigationManager.NavigateTo meghívással, amelyet a fejlesztői kód hív meg az URI-hoz való navigáláshoz. [NavigationManager Az API-t a következő cikkben, ASP.NET Core Blazor navigációban ismertetjük.]

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

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

Az OnNavigateAsynchasználatát bemutató példára lásd a ASP.NET Core Blazor WebAssemblylusta betöltésű összeállítások.

A kiszolgálón való előrendereléskor OnNavigateAsync végrehajtása kétszer:

• Egyszer, amikor a kért végpont összetevő kezdetben statikusan lett megjelenítve.
• Másodszor, amikor a böngésző megjeleníti a végpont összetevőjét.

A OnNavigateAsync fejlesztői kódjának kétszeri végrehajtásának megakadályozása érdekében a Routes összetevő tárolhatja a NavigationContext a OnAfterRender{Async} életciklus-metódusban, ahol firstRender ellenőrizhető. További információ: Prerendering with JavaScript interop.

Lemondások kezelése a OnNavigateAsync

A NavigationContext objektum, amelyet a OnNavigateAsync visszahívásnak adnak át, tartalmaz egy CancellationToken-t, amely beállításra kerül, amikor új navigációs esemény történik. A OnNavigateAsync visszahívásnak a megszakítási token beállításakor kivételt kell dobnia, hogy elkerülje a OnNavigateAsync visszahívás futtatását elavult navigáció esetén.

Ha egy felhasználó egy végpontra navigál, de azonnal egy új végpontra navigál, az alkalmazásnak nem szabad folytatnia az első végpont OnNavigateAsync visszahívását.

Az alábbi példában:

• A lemondási token a PostAsJsonAsynchívásakor van átadva, amely megszakíthatja a POST műveletet, ha a felhasználó elhagyja a /about végpontot.
• A megszakítási token be van állítva egy termékelőtöltési művelet során, ha a felhasználó ellép a /store végponttól.

@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);
            }
        }
    }
}

Jegyzet

Ha a NavigationContext megszakítási token megszakad, és nem dobunk kivételt, az nem szándékos viselkedést eredményezhet, például egy összetevő megjelenítését egy korábbi navigációból.

Felhasználói interakció <Navigating> tartalommal

Ha a navigálás során jelentős késés tapasztalható, például egy Blazor WebAssembly alkalmazás lusta betöltésű könyvtárait töltjük be vagy lassú hálózati kapcsolat van egy kiszolgálóoldali alkalmazással, a Blazor összetevő jelezheti a felhasználónak, hogy oldalváltás történik.

A Router összetevőt meghatározó összetevő tetején adjon hozzá egy @using irányelvet a Microsoft.AspNetCore.Components.Routing névtérhez:

@using Microsoft.AspNetCore.Components.Routing

Adjon meg tartalmat a Navigating paraméternek az oldaláttűnési események során való megjelenítéshez.

Az útválasztó elem (<Router>...</Router>) tartalma:

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

A Navigating tulajdonságot használó példáért lásd a késleltetett betöltésű szerelvényeket ASP.NET Core Blazor WebAssemblyalatt.