ASP.NET Core Razor összetevőinek felhasználása egy Razor osztálytárból (RCL)

Az összetevők megoszthatók egy Razor osztálytárban (RCL) a projektek között. Összetevők és statikus objektumok belefoglalása egy alkalmazásba a következő forrásból:

• A megoldás egy másik projektje.
• Hivatkozott .NET-kódtár.
• Egy NuGet-csomag.

Ahogyan az összetevők normál .NET-típusok, az RCL által biztosított összetevők is normál .NET-szerelvények.

RCL létrehozása

Visual Studio

1. Hozzon létre egy új projektet.
2. Az Új projekt létrehozása párbeszédpanelen válassza Razor Osztálytár az ASP.NET Core-projektsablonok listájából. Válassza Következőlehetőséget.
3. Az Új projekt konfigurálása párbeszédpanelen adjon meg egy projektnevet a Projektnév mezőben. A jelen témakörben szereplő példák a projekt nevét ComponentLibraryhasználják. Válassza Következőlehetőséget.
4. A További információk párbeszédpanelen ne válassza a Támogatási lapok és nézeteklehetőséget. Válassza a Létrehozás lehetőséget.
5. Adja hozzá az RCL-t egy megoldáshoz:
   1. Nyissa meg a megoldást.
   2. Kattintson a jobb gombbal a megoldásra Megoldáskezelő. Válassza Meglévő projekt>hozzáadásalehetőséget.
   3. Lépjen az RCL projektfájljára.
   4. Válassza ki az RCL projektfájlját (.csproj).
6. Adjon hozzá egy hivatkozást az RCL-hez az alkalmazásból:
   1. Kattintson a jobb gombbal az alkalmazásprojektre. Válassza >projekthivatkozásihozzáadása lehetőséget.
   2. Válassza ki az RCL-projektet. Válassza OKlehetőséget.

Visual Studio Code/ .NET CLI

1. Használja az Razor Osztálytár projektsablont (razorclasslib) a parancshéjban található dotnet new paranccsal. Az alábbi példában egy RCL jön létre és ComponentLibrary néven létrejön a -o|--output opcióval. A ComponentLibrary tartalmazó mappa automatikusan létrejön a parancs végrehajtásakor:

   dotnet new razorclasslib -o ComponentLibrary
   

2. Ha hozzá szeretné adni a kódtárat egy meglévő projekthez, használja a dotnet add reference parancsot egy parancshéjban. Az alábbi parancsban a {PATH TO LIBRARY} helyőrző a tár projektmappájának elérési útja:

   dotnet add reference {PATH TO LIBRARY}
   

RCL-ből egy Razor összetevőt felhasználni

Ha egy RCL-ből származó összetevőket szeretne felhasználni egy másik projektben, használja az alábbi módszerek egyikét:

• Használja a teljes összetevőtípus nevét, amely tartalmazza az RCL névterét.
• Az egyes összetevők az RCL névtere nélkül is hozzáadhatók, ha Razor@using irányelv deklarálja az RCL névterét. Használja az alábbi módszereket:
  • Adja hozzá a @using direktívát az egyes összetevőkhöz.
  • a @using irányelv belefoglalása a legfelső szintű _Imports.razor fájlba, hogy a kódtár összetevői egy teljes projekt számára elérhetővé legyenek. Adja hozzá az irányelvet egy _Imports.razor fájlhoz bármilyen szinten, hogy a névteret egyetlen összetevőre vagy összetevőkészletre alkalmazza egy mappán belül. Ha _Imports.razor fájlt használ, az egyes összetevők nem igényelnek @using irányelvet az RCL névteréhez.

Az alábbi példákban ComponentLibrary egy RCL, amely a Component1 összetevőt tartalmazza. A Component1 összetevő egy példaösszetevő, amely automatikusan hozzáadódik az RCL-projektsablonból létrehozott RCL-hez, amely nem lapok és nézetek támogatásához jön létre.

Component1.razor az ComponentLibrary RCL-ben:

<div class="my-component">
    This component is defined in the <strong>ComponentLibrary</strong> package.
</div>

Az RCL-t használó alkalmazásban hivatkozzon a Component1 összetevőre a névtér használatával, ahogyan az az alábbi példában is látható.

ConsumeComponent1.razor:

@page "/consume-component-1"

<h1>Consume component (full namespace example)</h1>

<ComponentLibrary.Component1 />

Másik lehetőségként adjon hozzá egy @using direktívát, és használja az összetevőt névtér nélkül. Az alábbi @using direktíva az aktuális mappában lévő vagy fölötti _Imports.razor fájlban is megjelenhet.

ConsumeComponent2.razor:

@page "/consume-component-2"
@using ComponentLibrary

<h1>Consume component (<code>@@using</code> example)</h1>

<Component1 />

Az CSS-elkülönítésihasználó kódtár-összetevők esetében a rendszer automatikusan elérhetővé teszi az összetevőstílusokat a fogyasztó alkalmazás számára. A tárat használó alkalmazásban nem szükséges manuálisan összekapcsolni vagy importálni a kódtár egyes összetevő-stíluslapjait vagy annak csomagban lévő CSS-fájlját. Az alkalmazás CSS-importálással hivatkozik az RCL csomagolt stílusára. A csomagban lévő stílusok nem jelennek meg a tárat használó alkalmazás statikus webes objektumaként. Egy ClassLib nevű osztálytár és egy Blazor stíluslapot tartalmazó BlazorSample.styles.css-alkalmazás esetén az RCL stíluslapja automatikusan importálódik az alkalmazás stíluslapjának tetején a létrehozáskor:

@import '_content/ClassLib/ClassLib.bundle.scp.css';

Az előző példákban Component1stíluslapja (Component1.razor.css) automatikusan össze van csomagolva.

Component1.razor.css az ComponentLibrary RCL-ben:

.my-component {
    border: 2px dashed red;
    padding: 1em;
    margin: 1em 0;
    background-image: url('background.png');
}

A háttérképet az RCL-projektsablon is tartalmazza, és az RCL wwwroot mappájában található.

wwwroot/background.png az ComponentLibrary RCL-ben:

Annak érdekében, hogy a könyvtár wwwroot mappájában található stíluslapok közül további könyvtári összetevő stílusokat biztosítson, adja hozzá a <link> stíluslap címkéket az RCL-felhasználóhoz, ahogy azt a következő példa mutatja.

Fontos

A könyvtári összetevők általában a CSS-elkülönítést használják az összetevőstílusok kötegeléséhez és biztosításához. A CSS-elkülönítésre támaszkodó összetevőstílusok automatikusan elérhetővé válnak az RCL-t használó alkalmazás számára. A tárat használó alkalmazásban nem szükséges manuálisan összekapcsolni vagy importálni a kódtár egyes összetevő-stíluslapjait vagy annak csomagban lévő CSS-fájlját. Az alábbi példa a globális stíluslapok biztosítására szolgál a CSS-elkülönítés-en kívül , ami általában nem követelmény a tipikus, RCL-eket használó alkalmazások esetében.

A következő példában a következő háttérképet használjuk. Ha implementálja az ebben a szakaszban látható példát, kattintson a jobb gombbal a képre a helyi mentéshez.

wwwroot/extra-background.png az ComponentLibrary RCL-ben:

Adjon hozzá egy új stíluslapot az RCL-hez egy extra-style osztálysal.

wwwroot/additionalStyles.css az ComponentLibrary RCL-ben:

.extra-style {
    border: 2px dashed blue;
    padding: 1em;
    margin: 1em 0;
    background-image: url('extra-background.png');
}

Adjon hozzá egy összetevőt a extra-style osztályt használó RCL-hez.

ExtraStyles.razor az ComponentLibrary RCL-ben:

<div class="extra-style">
    <p>
        This component is defined in the <strong>ComponentLibrary</strong> package.
    </p>
</div>

Adjon hozzá egy lapot az alkalmazáshoz, amely az RCL ExtraStyles összetevőjét használja.

ConsumeComponent3.razor:

@page "/consume-component-3"
@using ComponentLibrary

<h1>Consume component (<code>additionalStyles.css</code> example)</h1>

<ExtraStyles />

Hivatkozás a könyvtár stíluslapjára az alkalmazás <head> jelölésében (hely szerint a <head> tartalomban):

Blazor Web App:

<link href="@Assets["_content/ComponentLibrary/additionalStyles.css"]" rel="stylesheet">

Különálló Blazor WebAssembly alkalmazások:

<link href="_content/ComponentLibrary/additionalStyles.css" rel="stylesheet">

Routable-összetevők elérhetővé tétele az RCL-ből

Ahhoz, hogy az RCL-ben elérhető útválasztható összetevők közvetlenül elérhetők legyenek, az RCL összeállítását közzé kell tenni az alkalmazás útválasztóján.

Nyissa meg az alkalmazás App összetevőjét (App.razor). Rendeljen hozzá egy Assembly gyűjteményt a AdditionalAssemblies összetevő Router paraméteréhez az RCL összeállításának belefoglalásához. Az alábbi példában a ComponentLibrary.Component1 összetevő az RCL szerelvényének felderítésére szolgál.

AdditionalAssemblies="new[] { typeof(ComponentLibrary.Component1).Assembly }"

További információért lásd: ASP.NET Core Blazor útválasztás és navigáció.

RCL létrehozása statikus eszközökkel a wwwroot mappában

Az RCL statikus eszközei minden olyan alkalmazás számára elérhetők, amely a tárat használja.

Helyezze a statikus objektumokat az RCL wwwroot mappájába, és hivatkozzon a statikus objektumokra az alkalmazás következő elérési útján: _content/{PACKAGE ID}/{PATH AND FILE NAME}. A {PACKAGE ID} helyőrző a könyvtár csomagazonosítója. A csomagazonosító alapértelmezés szerint a projekt összeállítási neve lesz, ha <PackageId> nincs megadva a projektfájlban. A {PATH AND FILE NAME} helyőrző az elérési út és a fájl neve, amely az wwwrootalatt található. Ez az elérésiút-formátum az RCL-hez hozzáadott NuGet-csomagok által biztosított statikus objektumokhoz is használható az alkalmazásban.

Az alábbi példa az RCL statikus eszközök használatát mutatja be egy ComponentLibrary nevű RCL-vel és egy Blazor-alkalmazással, amely az RCL-t használja. Az alkalmazás rendelkezik egy projekthivatkozással a ComponentLibrary RCL-hez.

A jelen szakasz példájában az alábbi Jeep-rendszerképet® használjuk. Ha implementálja az ebben a szakaszban látható példát, kattintson a jobb gombbal a képre a helyi mentéshez.

wwwroot/jeep-yj.png az ComponentLibrary RCL-ben:

Adja hozzá a következő JeepYJ összetevőt az RCL-hez.

JeepYJ.razor az ComponentLibrary RCL-ben:

<h3>ComponentLibrary.JeepYJ</h3>

<p>
    <img alt="Jeep YJ&reg;" src="_content/ComponentLibrary/jeep-yj.png" />
</p>

Adja hozzá a következő Jeep összetevőt az ComponentLibrary RCL-t használó alkalmazáshoz. A Jeep összetevő a következőket használja:

• A ComponentLibrary RCL wwwroot mappájából származó Jeep YJ® kép.
• A JeepYJ összetevő az RCL-ből.

Jeep.razor:

@page "/jeep"
@using ComponentLibrary

<div style="float:left;margin-right:10px">
    <h3>Direct use</h3>

    <p>
        <img alt="Jeep YJ&reg;" src="_content/ComponentLibrary/jeep-yj.png" />
    </p>
</div>

<JeepYJ />

<p>
    <em>Jeep</em> and <em>Jeep YJ</em> are registered trademarks of 
    <a href="https://www.stellantis.com">FCA US LLC (Stellantis NV)</a>.
</p>

Renderelt Jeep összetevő:

További információért lásd:ÚjrahasználhatóRazor felhasználói felület ASP.NET Core osztálykönyvtárakban.

RCL létrehozása összetevőkkel csoportosított JavaScript-fájlokkal

A JavaScript (JS) fájlok Razor komponensekhez való társítása kényelmes módja a szkriptek alkalmazáson belüli rendszerezésének.

Razor Blazor-alkalmazások összetevői a JS kiterjesztésű fájlokat rendezetten kezelik, és ezek a fájlok nyilvánosan címezhetők a projektbeli fájl elérési útját használva.

{PATH}/{COMPONENT}.razor.js

• A {PATH} helyőrző az összetevő elérési útja.
• A {COMPONENT} helyőrző az összetevő.

Az alkalmazás közzétételekor a keretrendszer automatikusan áthelyezi a szkriptet a webgyökérbe. A szkriptek át lesznek helyezve a bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.js-ba, ahol találhatók a helyőrzők.

• {TARGET FRAMEWORK MONIKER} a célkeretrendszer-moniker (TFM).
• {PATH} az összetevő elérési útja.
• {COMPONENT} az összetevő neve.

A szkript relatív URL-címén nem szükséges változtatni, mivel Blazor gondoskodik arról, hogy a JS fájl közzétett statikus elemek közé kerüljön.

Ez a szakasz és a következő példák elsősorban a JS fájlelhelyezés magyarázatára összpontosítanak. Az első példa egy JS fájlt mutat be egy általános JS függvénnyel. A második példa egy modul függvény betöltésére való használatát mutatja be, amely a legtöbb éles alkalmazás esetében ajánlott módszer. A .NET-ből a JS hívása teljes mértékben lefedett a „JavaScript-függvények meghívása .NET-metódusokból az ASP.NET Core-ban” Blazorcímen, ahol a BlazorJS API további magyarázatait találjuk, kiegészítve példákkal. A második példában jelen lévő komponens ártalmatlanítása az ASP.NET Core Razor komponens ártalmatlanításvan tárgyalva.

Az alábbi JsCollocation1 összetevő betölt egy szkriptet egy HeadContent összetevőn keresztül, és meghív egy JS függvényt IJSRuntime.InvokeAsync. A {PATH} helyőrző az összetevő elérési útja.

Fontos

Ha a következő kódot használja egy tesztalkalmazás bemutatójára, módosítsa a {PATH} helyőrzőt az összetevő elérési útjára (például: .NET 8-ban vagy újabb verzióban Components/Pages vagy a .NET 7-ben vagy korábbi verziókban Pages). Egy Blazor Web App (.NET 8 vagy újabb verzió) az összetevőhöz az alkalmazásra vagy az összetevő definícióra globálisan alkalmazott interaktív renderelési mód szükséges.

Adja hozzá a következő szkriptet a Blazor szkript után (a Blazor indítási szkript helyét):

<script src="{PATH}/JsCollocation1.razor.js"></script>

JsCollocation1 összetevő ({PATH}/JsCollocation1.razor):

@page "/js-collocation-1"
@inject IJSRuntime JS

<PageTitle>JS Collocation 1</PageTitle>

<h1>JS Collocation Example 1</h1>

<button @onclick="ShowPrompt">Call showPrompt1</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

@code {
    private string? result;

    public async Task ShowPrompt()
    {
        result = await JS.InvokeAsync<string>(
            "showPrompt1", "What's your name?");
        StateHasChanged();
    }
}

Az csoportosított JS fájl a JsCollocation1 összetevőfájl mellett található, és a fájl neve JsCollocation1.razor.js. Az JsCollocation1 összetevőben a szkript az csoportosított fájl elérési útjára hivatkozik. Az alábbi példában a showPrompt1 függvény elfogadja a felhasználó nevét egy Window prompt(), és visszaadja a JsCollocation1 összetevőnek megjelenítésre.

{PATH}/JsCollocation1.razor.js:

function showPrompt1(message) {
  return prompt(message, 'Type your name here');
}

Az előző megközelítés nem ajánlott az éles alkalmazásokban való általános használathoz, mert a megközelítés globális függvényekkel szennyezi az ügyfelet. Az éles alkalmazások esetében jobb megközelítés a JS modulok használata. Ugyanezek az általános alapelvek vonatkoznak egy JS modul egy csoportosított JS fájlból való betöltésére, ahogyan azt a következő példa is mutatja.

Az alábbi JsCollocation2 összetevő OnAfterRenderAsync metódusa betölt egy JS modult a module-ba, amely az összetevő osztály IJSObjectReference. module a showPrompt2 függvény meghívására szolgál. A {PATH} helyőrző az összetevő elérési útja.

Fontos

Ha a következő kódot használja egy tesztalkalmazásban történő bemutatóhoz, módosítsa a {PATH} helyőrzőt az összetevő elérési útjára. Egy Blazor Web App (.NET 8 vagy újabb verzió) az összetevőhöz az alkalmazásra vagy az összetevő definícióra globálisan alkalmazott interaktív renderelési mód szükséges.

JsCollocation2 összetevő ({PATH}/JsCollocation2.razor):

@page "/js-collocation-2"
@implements IAsyncDisposable
@inject IJSRuntime JS

<PageTitle>JS Collocation 2</PageTitle>

<h1>JS Collocation Example 2</h1>

<button @onclick="ShowPrompt">Call showPrompt2</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

@code {
    private IJSObjectReference? module;
    private string? result;

    protected async override Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            /*
                Change the {PATH} placeholder in the next line to the path of
                the collocated JS file in the app. Examples:

                ./Components/Pages/JsCollocation2.razor.js (.NET 8 or later)
                ./Pages/JsCollocation2.razor.js (.NET 7 or earlier)
            */
            module = await JS.InvokeAsync<IJSObjectReference>("import",
                "./{PATH}/JsCollocation2.razor.js");
        }
    }

    public async Task ShowPrompt()
    {
        if (module is not null)
        {
            result = await module.InvokeAsync<string>(
                "showPrompt2", "What's your name?");
            StateHasChanged();
        }
    }

    async ValueTask IAsyncDisposable.DisposeAsync()
    {
        if (module is not null)
        {
            try
            {
                await module.DisposeAsync();
            }
            catch (JSDisconnectedException)
            {
            }
        }
    }
}

Az előző példában a JSDisconnectedException elakad a modul eltávolítása során, ha a BlazorSignalR körzete elveszik. Ha az előző kódot egy Blazor WebAssembly alkalmazásban használják, nincs elveszítendő SignalR kapcsolat, így el lehet távolítani a try-catch blokkot, és meghagyhatja a modult (await module.DisposeAsync();) megsemmisítő sort. További információ: ASP.NET Core Blazor JavaScript-együttműködés (JS interop).

{PATH}/JsCollocation2.razor.js:

export function showPrompt2(message) {
  return prompt(message, 'Type your name here');
}

Fontos

Ne tegyen <script> címkét JsCollocation2.razor.js a Blazor szkript után, mert a modul automatikusan betöltődik és gyorsítótárazódik, amikor a dinamikus import() meghívásra kerül.

A szkriptek és modulok használata a JS osztálykönyvtárban (RCL) elhelyezett Razor esetén csak a BlazorJS interop mechanizmusa által támogatott, amely a IJSRuntime interfészen alapul. Ha JavaScript [JSImport]/[JSExport] interop-t valósít meg, tekintse meg a JavaScript JSImport/JSExport interműködését az ASP.NET Core-ral Blazor.

Az Razor osztálykódtár (RCL) által IJSRuntime-alapú JS interop használatával biztosított szkriptek vagy modulok esetében a következő elérési utat használja a rendszer:

./_content/{PACKAGE ID}/{PATH}/{COMPONENT}.{EXTENSION}.js

• Az aktuális könyvtár elérési útja (./) szükséges a megfelelő statikus objektum elérési útjának létrehozásához a JS fájlhoz.
• A {PACKAGE ID} helyőrző az RCL csomagazonosítója (vagy az alkalmazás által hivatkozott osztálytár könyvtárneve).
• A {PATH} helyőrző az összetevő elérési útja. Ha egy Razor összetevő az RCL gyökerénél található, az elérésiút-szegmens nem lesz benne.
• A {COMPONENT} helyőrző az összetevő neve.
• A {EXTENSION} helyőrző megegyezik az összetevő kiterjesztésével, razor vagy cshtml.

Az alábbi Blazor alkalmazás példája:

• Az RCL csomagazonosítója AppJS.
• A modul szkriptjei betöltődtek a JsCollocation3 összetevőhöz (JsCollocation3.razor).
• A JsCollocation3 összetevő az RCL Components/Pages mappájában található.

module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./_content/AppJS/Components/Pages/JsCollocation3.razor.js");

Ügyféloldali böngészőkompatibilitás-elemző

Az ügyféloldali alkalmazások a teljes .NET API-felületet célják, de a böngésző tesztkörnyezeti korlátozásai miatt nem minden .NET API támogatott a WebAssemblyben. A nem támogatott API-k PlatformNotSupportedException dobnak a WebAssemblyen való futtatáskor. A platformkompatibilitás-elemző figyelmezteti a fejlesztőt, ha az alkalmazás olyan API-kat használ, amelyeket az alkalmazás célplatformjai nem támogatnak. Az ügyféloldali alkalmazások esetében ez azt jelenti, hogy az API-k támogatottak a böngészőkben. A kompatibilitáselemző .NET-keretrendszer API-inak jegyzetelése folyamatban van, ezért jelenleg nem minden .NET-keretrendszer API van jegyzetelve.

Az interaktív WebAssembly-összetevőket, Blazor Web App alkalmazásokat és RCL-projekteket lehetővé tevő Blazor WebAssemblyelemek automatikusan engedélyezik a böngészőkompatibilitási ellenőrzéseket azáltal, hogy browser támogatott platformként hozzáadják a SupportedPlatform MSBuild elemhez. A kódtár fejlesztői manuálisan is hozzáadhatják a SupportedPlatform elemet egy erőforrástár projektfájljába a funkció engedélyezéséhez:

<ItemGroup>
  <SupportedPlatform Include="browser" />
</ItemGroup>

Egy kódtár létrehozásakor jelezze, hogy egy adott API nem támogatott a böngészőkben a browserUnsupportedOSPlatformAttribute megadásával:

using System.Runtime.Versioning;

...

[UnsupportedOSPlatform("browser")]
private static string GetLoggingDirectory()
{
    ...
}

További információ: Az API-k jegyzetelése adott platformokon nem támogatottként (dotnet/designs GitHub-adattár).

JavaScript-elkülönítés JavaScript-modulokban

Blazor javaScript-elkülönítést tesz lehetővé standard JavaScript-modulokban. A JavaScript-elkülönítés a következő előnyöket biztosítja:

• Az importált JavaScript már nem szennyezi a globális névteret.
• A kódtár és az összetevők felhasználóinak nem kell manuálisan importálniuk a kapcsolódó JavaScriptet.

További információ: JavaScript-függvények meghívása a .NET-metódusokból ASP.NET Core Blazor.

Kerülje a JavaScript által meghívható .NET metódusok eltávolítását.

Futtatókörnyezet újracsatolása eltávolítja az osztálypéldány JavaScript által meghívható .NET metódusait, hacsak nincsenek kifejezetten megőrizve. További információ: .NET-metódusok meghívása JavaScript-függvényekből a ASP.NET Core Blazor.

Építés, csomagolás és publikálás a NuGetre

Mivel RazorRazor összetevőket tartalmazó osztálykódtárak standard .NET-kódtárak, a NuGetbe való csomagolás és szállítás nem különbözik a nuGet-tárak csomagolásától és szállításától. A csomagolás a parancssor környezetében dotnet pack parancsával történik meg:

dotnet pack

Töltse fel a csomagot a NuGetbe a parancshéjban található dotnet nuget push paranccsal.

Védjegyek

Jeep és Jeep YJFCA US LLC (Stellantis NV)bejegyzett védjegyei.

További erőforrások

• Újrahasználható Razor felhasználói felület osztálykönyvtárakban az ASP.NET Core segítségével
• ASP.NET Core API-k használata osztálykönyvtárban
• XML Intermediate Language (IL) vágókonfigurációs fájl hozzáadása egy könyvtárhoz
• CSS-elkülönítés támogatása Razor osztálykódtárakkal