ASP.NET Core Razor-componenten uit een Razor class library (RCL) gebruiken

Onderdelen kunnen worden gedeeld in een Razor klassebibliotheek (RCL) tussen projecten. Onderdelen en statische assets opnemen in een app van:

• Een ander project in de oplossing.
• Een .NET-bibliotheek waarnaar wordt verwezen.
• Een NuGet-pakket.

Net zoals onderdelen reguliere .NET-typen zijn, zijn onderdelen die worden geleverd door een RCL normale .NET-assembly's.

Een RCL maken

Visual Studio-

1. Maak een nieuw project.
2. Selecteer in het dialoogvenster Een nieuw project makenRazor Klassebibliotheek in de lijst met ASP.NET Core-projectsjablonen. Selecteer Volgende.
3. Geef in het dialoogvenster Uw nieuwe project configureren een projectnaam op in het veld Projectnaam. In voorbeelden in dit onderwerp wordt de projectnaam ComponentLibrarygebruikt. Selecteer Volgende.
4. Selecteer niet ondersteuningspagina's en weergavenin het dialoogvenster Aanvullende informatie. Selecteer maken.
5. Voeg de RCL toe aan een oplossing:
   1. Open de oplossing.
   2. Klik met de rechtermuisknop op de oplossing in Solution Explorer. Selecteer >bestaand project toevoegen.
   3. Navigeer naar het projectbestand van de RCL.
   4. Selecteer het projectbestand van de RCL (.csproj).
6. Voeg een verwijzing toe naar de RCL vanuit de app:
   1. Klik met de rechtermuisknop op het app-project. Selecteer >projectreferentie toevoegen.
   2. Selecteer het RCL-project. Selecteer OK-.

Visual Studio Code/.NET CLI-

1. Gebruik de Razor class-bibliotheek projectsjabloon (razorclasslib) met de opdracht dotnet new in een commandoshell. In het volgende voorbeeld wordt een RCL gemaakt en benoemd ComponentLibrary met behulp van de optie -o|--output. De map met ComponentLibrary wordt automatisch gemaakt wanneer de opdracht wordt uitgevoerd:

   dotnet new razorclasslib -o ComponentLibrary
   

2. Als u de bibliotheek wilt toevoegen aan een bestaand project, gebruikt u de opdracht dotnet add reference in een opdrachtshell. In de volgende opdracht is de tijdelijke aanduiding {PATH TO LIBRARY} het pad naar de projectmap van de bibliotheek:

   dotnet add reference {PATH TO LIBRARY}
   

Een Razor-onderdeel van een RCL gebruiken

Als u onderdelen van een RCL in een ander project wilt gebruiken, gebruikt u een van de volgende methoden:

• Gebruik de volledige naam van het onderdeeltype, die de naamruimte van de RCL bevat.
• Afzonderlijke onderdelen kunnen op naam worden toegevoegd zonder de naamruimte van de RCL, als de Razor's @using-instructie de naamruimte van de RCL beschrijft. Gebruik de volgende methoden:
  • Voeg de @using-instructie toe aan afzonderlijke onderdelen.
  • neem de @using instructie op in het _Imports.razor-bestand op het hoogste niveau om de onderdelen van de bibliotheek beschikbaar te maken voor een volledig project. Voeg de instructie toe aan een _Imports.razor-bestand op elk niveau om de naamruimte toe te passen op één onderdeel of set onderdelen in een map. Wanneer een _Imports.razor-bestand wordt gebruikt, hebben afzonderlijke onderdelen geen @using-instructie nodig voor de naamruimte van de RCL.

In de volgende voorbeelden is ComponentLibrary een RCL die het Component1-onderdeel bevat. Het Component1 onderdeel is een voorbeeldonderdeel dat automatisch wordt toegevoegd aan een RCL die is gemaakt op basis van de RCL-projectsjabloon die niet is gemaakt ter ondersteuning van pagina's en weergaven.

Component1.razor in de ComponentLibrary RCL:

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

In de app die de RCL gebruikt, verwijst u naar het Component1 onderdeel met behulp van de naamruimte, zoals in het volgende voorbeeld wordt weergegeven.

ConsumeComponent1.razor:

@page "/consume-component-1"

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

<ComponentLibrary.Component1 />

U kunt ook een @using instructie toevoegen en het onderdeel zonder de naamruimte ervan gebruiken. De volgende @using-instructie kan ook voorkomen in elk _Imports.razor-bestand op of boven de huidige map.

ConsumeComponent2.razor:

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

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

<Component1 />

Voor bibliotheekonderdelen die gebruikmaken van CSS-isolatie, worden de onderdeelstijlen automatisch beschikbaar gemaakt voor de verbruikende app. U hoeft de afzonderlijke opmaakmodellen voor onderdelen of het gebundelde CSS-bestand van de bibliotheek niet handmatig te koppelen of te importeren in de app die de bibliotheek gebruikt. De app maakt gebruik van CSS-importbewerkingen om te verwijzen naar de gebundelde stijlen van de RCL. De gebundelde stijlen worden niet gepubliceerd als een statisch web-item van de app die de bibliotheek gebruikt. Voor een klassebibliotheek met de naam ClassLib en een Blazor-app met een BlazorSample.styles.css-stijlblad, wordt het stijlblad van de RCL automatisch bovenaan het stijlblad van de app geïmporteerd bij het opbouwen.

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

Voor de voorgaande voorbeelden wordt het opmaakmodel van Component1(Component1.razor.css) automatisch gebundeld.

Component1.razor.css in de ComponentLibrary RCL:

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

De achtergrondafbeelding is ook opgenomen in de RCL-projectsjabloon en bevindt zich in de map wwwroot van de RCL.

wwwroot/background.png in de ComponentLibrary RCL:

Als u extra stijlen voor componenten van de bibliotheek wilt opgeven uit style sheets in de map wwwroot van de bibliotheek, voegt u style sheet <link> tags toe aan de gebruiker van de RCL, zoals in het volgende voorbeeld wordt gedemonstreerd.

Belangrijk

Over het algemeen gebruiken bibliotheekonderdelen CSS-isolatie om onderdeelstijlen te bundelen en aan te bieden. Onderdeelstijlen die afhankelijk zijn van CSS-isolatie, worden automatisch beschikbaar gesteld aan de app die gebruikmaakt van de RCL. U hoeft de afzonderlijke opmaakmodellen voor onderdelen of het gebundelde CSS-bestand van de bibliotheek niet handmatig te koppelen of te importeren in de app die de bibliotheek gebruikt. Het volgende voorbeeld is voor het leveren van globale opmaakmodellen buiten CSS-isolatie, wat meestal geen vereiste is voor typische apps die RCL's gebruiken.

In het volgende voorbeeld wordt de volgende achtergrondafbeelding gebruikt. Als u het voorbeeld in deze sectie implementeert, klikt u met de rechtermuisknop op de afbeelding om deze lokaal op te slaan.

wwwroot/extra-background.png in de ComponentLibrary RCL:

Voeg een nieuw opmaakmodel toe aan de RCL met een extra-style-klasse.

wwwroot/additionalStyles.css in de ComponentLibrary RCL:

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

Voeg een onderdeel toe aan de RCL die gebruikmaakt van de extra-style-klasse.

ExtraStyles.razor in de ComponentLibrary RCL:

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

Voeg een pagina toe aan de app die gebruikmaakt van het ExtraStyles-onderdeel van de RCL.

ConsumeComponent3.razor:

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

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

<ExtraStyles />

Link naar de stylesheet van de bibliotheek in de <head> opmaak van de app (locatie van <head> inhoud):

Blazor Web Apps:

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

Zelfstandige Blazor WebAssembly-apps:

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

Routeerbare onderdelen beschikbaar maken vanuit de RCL

Als u routeerbare onderdelen in de RCL beschikbaar wilt maken voor directe aanvragen, moet de assembly van de RCL worden vrijgegeven aan de router van de app.

Open het App-onderdeel van de app (App.razor). Wijs een Assembly collectie toe aan de AdditionalAssemblies parameter van het Router onderdeel om het samenstel van de RCL op te nemen. In het volgende voorbeeld wordt het ComponentLibrary.Component1-onderdeel gebruikt om de assembly van de RCL te detecteren.

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

Zie ASP.NET Core Blazor routering en navigatievoor meer informatie.

Een RCL maken met statische assets in de map wwwroot

De statische assets van een RCL zijn beschikbaar voor elke app die de bibliotheek verbruikt.

Plaats statische assets in de map wwwroot van de RCL en verwijs naar de statische assets met het volgende pad in de app: _content/{PACKAGE ID}/{PATH AND FILE NAME}. De tijdelijke aanduiding {PACKAGE ID} is de pakket-id van de bibliotheek. De pakket-id wordt standaard ingesteld op de assemblynaam van het project als <PackageId> niet is opgegeven in het projectbestand. De tijdelijke aanduiding {PATH AND FILE NAME} is het pad en de bestandsnaam onder wwwroot. Deze padindeling wordt ook gebruikt in de app voor statische assets die worden geleverd door NuGet-pakketten die zijn toegevoegd aan de RCL.

In het volgende voorbeeld ziet u het gebruik van statische RCL-assets met een RCL met de naam ComponentLibrary en een Blazor-app die de RCL verbruikt. De app heeft een projectreferentie voor de ComponentLibrary RCL.

De volgende Jeep-afbeelding® wordt gebruikt in het voorbeeld van deze sectie. Als u het voorbeeld in deze sectie implementeert, klikt u met de rechtermuisknop op de afbeelding om deze lokaal op te slaan.

wwwroot/jeep-yj.png in de ComponentLibrary RCL:

Voeg het volgende JeepYJ onderdeel toe aan de RCL.

JeepYJ.razor in de ComponentLibrary RCL:

<h3>ComponentLibrary.JeepYJ</h3>

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

Voeg het volgende Jeep-onderdeel toe aan de app die de ComponentLibrary RCL gebruikt. Het Jeep-onderdeel maakt gebruik van:

• De Jeep YJ-afbeelding® uit de wwwroot map van de ComponentLibrary RCL.
• Het JeepYJ onderdeel van de RCL.

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>

Jeep-onderdeel weergegeven:

Zie Herbruikbare Razor gebruikersinterface in klassebibliotheken met ASP.NET Corevoor meer informatie.

Een RCL maken met JavaScript-bestanden die gegroepeerd zijn met componenten

Samenvoegen van JavaScript-bestanden (JS) voor Razor componenten is een handige manier om scripts in een app te organiseren.

Razor onderdelen van Blazor apps die JS bestanden samenvoegen met behulp van de .razor.js-extensie en openbaar adresseerbaar zijn met behulp van het pad naar het bestand in het project:

{PATH}/{COMPONENT}.razor.js

• De tijdelijke aanduiding {PATH} is het pad naar het onderdeel.
• De plaatsaanduiding {COMPONENT} is het onderdeel.

Wanneer de app wordt gepubliceerd, verplaatst het framework het script automatisch naar de webroot. Scripts worden verplaatst naar bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.js, waarbij de tijdelijke aanduidingen zijn:

• {TARGET FRAMEWORK MONIKER} is de Target Framework Moniker (TFM).
• {PATH} is het pad naar het onderdeel.
• {COMPONENT} is de naam van het onderdeel.

Er is geen wijziging vereist voor de relatieve URL van het script, omdat Blazor het JS bestand in gepubliceerde statische assets voor u plaatst.

Deze sectie en de volgende voorbeelden zijn voornamelijk gericht op het uitleggen van JS bestands collocatie. In het eerste voorbeeld ziet u een JS-bestand met een gewone JS-functie. In het tweede voorbeeld ziet u hoe een module wordt gebruikt om een functie te laden. Dit is de aanbevolen benadering voor de meeste productie-apps. Het aanroepen van JS vanuit .NET wordt volledig behandeld in JavaScript-functies aanroepen vanuit .NET-methoden in ASP.NET Core Blazor, waar de BlazorJS-API verder wordt uitgelegd met aanvullende voorbeelden. De verwijdering van componenten, die in het tweede voorbeeld aanwezig is, wordt behandeld in ASP.NET Core componentenlevenscyclusRazor.

Met het volgende JsCollocation1 onderdeel wordt een script geladen via een HeadContent-onderdeel en wordt een JS-functie aangeroepen met IJSRuntime.InvokeAsync. De tijdelijke aanduiding {PATH} is het pad naar het onderdeel.

Belangrijk

Als u de volgende code gebruikt voor een demonstratie in een test-app, wijzigt u de tijdelijke aanduiding {PATH} in het pad van het onderdeel (bijvoorbeeld: Components/Pages in .NET 8 of hoger of Pages in .NET 7 of eerder). In een Blazor Web App (.NET 8 of hoger) vereist het onderdeel een interactieve weergavemodus die globaal is toegepast op de app of op de definitie van het onderdeel.

Voeg het volgende script toe na het Blazor script (locatie van het Blazor startscript):

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

JsCollocation1 onderdeel ({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();
    }
}

Het JS-bestand wordt naast het JsCollocation1 onderdeelbestand geplaatst met de bestandsnaam JsCollocation1.razor.js. In het JsCollocation1-onderdeel wordt naar het script verwezen op het pad van het gelocaliseerde bestand. In het volgende voorbeeld accepteert de functie showPrompt1 de naam van de gebruiker van een Window prompt() en retourneert deze naar het JsCollocation1 onderdeel voor weergave.

{PATH}/JsCollocation1.razor.js:

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

De voorgaande benadering wordt niet aanbevolen voor algemeen gebruik in productie-apps, omdat de benadering de client vervuilt met globale functies. Een betere benadering voor productie-apps is het gebruik van JS modules. Dezelfde algemene principes zijn van toepassing op het laden van een JS-module uit een JS-bestand, zoals in het volgende voorbeeld wordt gedemonstreerde.

Met de OnAfterRenderAsync methode van het volgende JsCollocation2 onderdeel wordt een JS module in modulegeladen. Dit is een IJSObjectReference van de onderdeelklasse. module wordt gebruikt om de functie showPrompt2 aan te roepen. De tijdelijke aanduiding {PATH} is het pad naar het onderdeel.

Belangrijk

Als u de volgende code gebruikt voor een demonstratie in een test-app, wijzigt u de tijdelijke aanduiding {PATH} in het pad van het onderdeel. In een Blazor Web App (.NET 8 of hoger) vereist het onderdeel een interactieve weergavemodus die globaal is toegepast op de app of op de definitie van het onderdeel.

JsCollocation2 onderdeel ({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)
            {
            }
        }
    }
}

In het voorgaande voorbeeld wordt JSDisconnectedException vastgezet tijdens het afvoeren van de module als het SignalR-circuit van geval Blazorverloren gaat. Als de voorgaande code wordt gebruikt in een Blazor WebAssembly-app, is er geen SignalR verbinding verloren gegaan, zodat u het try-catch blok kunt verwijderen en de regel kunt verlaten waarmee de module (await module.DisposeAsync();) wordt verwijderd. Zie ASP.NET Core Blazor JavaScript-interoperabiliteit (JS interop)voor meer informatie.

{PATH}/JsCollocation2.razor.js:

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

Belangrijk

Plaats geen <script> tag voor JsCollocation2.razor.js na het Blazor script omdat de module automatisch wordt geladen en in de cache wordt opgeslagen wanneer de dynamische import() wordt aangeroepen.

Het gebruik van scripts en modules voor JS in een Razor klassebibliotheek (RCL) wordt alleen ondersteund voor BlazorJS interopmechanisme op basis van de IJSRuntime-interface. Als u JavaScript [JSImport]/[JSExport] interopimplementeert, zie JavaScript JSImport/JSExport-interop met ASP.NET Core Blazor.

Voor scripts of modules die worden geleverd door een Razor klassebibliotheek (RCL) met behulp van IJSRuntimeJS interop, wordt het volgende pad gebruikt:

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

• Het padsegment voor de huidige directory (./) is vereist om het correcte pad voor statische assets naar het JS-bestand aan te maken.
• De tijdelijke aanduiding {PACKAGE ID} is de pakket-id van de RCL (of bibliotheeknaam voor een klassebibliotheek waarnaar wordt verwezen door de app).
• De tijdelijke aanduiding {PATH} is het pad naar het onderdeel. Als een Razor-onderdeel zich in de wortelmap van de RCL bevindt, wordt het padsegment niet opgenomen.
• De tijdelijke aanduiding {COMPONENT} is de naam van het onderdeel.
• De placeholder {EXTENSION} komt overeen met de extensie van de component, ofwel razor of cshtml.

In het volgende Blazor app-voorbeeld:

• De pakket-id van de RCL is AppJS.
• De scripts van een module worden geladen voor het JsCollocation3-onderdeel (JsCollocation3.razor).
• Het JsCollocation3 onderdeel bevindt zich in de map Components/Pages van de RCL.

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

Browsercompatibiliteitsanalyse aan de clientzijde

Client-side apps richten zich op het volledige oppervlak van de .NET-API, maar niet alle .NET-API's worden ondersteund op WebAssembly vanwege beperkingen door de sandbox in de browser. Niet-ondersteunde API's gooien PlatformNotSupportedException bij het uitvoeren op WebAssembly. Een platformcompatibiliteitsanalyse waarschuwt de ontwikkelaar wanneer de app API's gebruikt die niet worden ondersteund door de doelplatforms van de app. Voor apps aan de clientzijde betekent dit dat wordt gecontroleerd of API's worden ondersteund in browsers. Aantekeningen toevoegen aan .NET Framework-API's voor de compatibiliteitsanalyse is een doorgaand proces, dus niet alle .NET Framework-API wordt momenteel geannoteerd.

Blazor Web Appdie Interactieve WebAssembly-onderdelen, Blazor WebAssembly-apps en RCL-projecten inschakelen automatisch browsercompatibiliteitscontroles inschakelen door browser toe te voegen als een ondersteund platform met het SupportedPlatform MSBuild-item. Bibliotheekontwikkelaars kunnen het SupportedPlatform item handmatig toevoegen aan het projectbestand van een bibliotheek om de functie in te schakelen:

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

Bij het ontwerpen van een bibliotheek geeft u aan dat een bepaalde API niet wordt ondersteund in browsers door browser op te geven voor UnsupportedOSPlatformAttribute:

using System.Runtime.Versioning;

...

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

Voor meer informatie, zie API's annoteren als niet-ondersteund op specifieke platforms in dedotnet/designs GitHub-repository.

JavaScript-isolatie in JavaScript-modules

Blazor maakt JavaScript-isolatie mogelijk in standaard JavaScript-modules. JavaScript-isolatie biedt de volgende voordelen:

• Geïmporteerde JavaScript vervuilt de globale naamruimte niet meer.
• Gebruikers van de bibliotheek en onderdelen hoeven het gerelateerde JavaScript niet handmatig te importeren.

Zie JavaScript-functies aanroepen vanuit .NET-methoden in ASP.NET Core Blazorvoor meer informatie.

Vermijd het inkorten van .NET-methoden die door JavaScript kunnen worden opgeroepen.

Opnieuw koppelen tijdens runtime snijdt de .NET-methoden van het klasse-exemplaar die via JavaScript kunnen worden aangeroepen, bij, tenzij ze expliciet worden bewaard. Zie .NET-methoden aanroepen vanuit JavaScript-functies in ASP.NET Core Blazorvoor meer informatie.

Bouwen, verpakken en verzenden naar NuGet

Omdat Razor klassebibliotheken die Razor onderdelen bevatten, standaard .NET-bibliotheken zijn, is het inpakken en verzenden ervan naar NuGet niet anders dan het verpakken en verzenden van bibliotheken naar NuGet. Verpakking wordt uitgevoerd met behulp van de opdracht dotnet pack in een opdrachtshell:

dotnet pack

Upload het pakket naar NuGet met behulp van de opdracht dotnet nuget push in een opdrachtshell.

Handelsmerken

Jeep en Jeep YJ zijn gedeponeerde handelsmerken van FCA US LLC (Stellantis NV).

Aanvullende informatiebronnen

• Herbruikbare gebruikersinterface van Razor in klassebibliotheken met ASP.NET Core-
• ASP.NET Core-API's gebruiken in een klassebibliotheek
• een XML Intermediate Language (IL) Trimmer-configuratiebestand toevoegen aan een bibliotheek
• ondersteuning voor CSS-isolatie met Razor klassebibliotheken