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. Select Next.
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. Select Next.
4. In the Additional information dialog, don't select Support pages and views. Selecteer Aanmaken.
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. Select OK.

Visual Studio Code / .NET CLI

1. Use the Razor Class Library project template (razorclasslib) with the dotnet new command in a command shell. 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}
   

Consume a Razor component from an RCL

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 the 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. For a class library named ClassLib and a Blazor app with a BlazorSample.styles.css stylesheet, the RCL's stylesheet is imported at the top of the app's stylesheet automatically at build time:

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

For the preceding examples, Component1's stylesheet (Component1.razor.css) is bundled automatically.

Component1.razor.css in the 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 the ComponentLibrary RCL:

To provide additional library component styles from stylesheets in the library's wwwroot folder, add stylesheet <link> tags to the RCL's consumer, as the next example demonstrates.

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 the ComponentLibrary RCL:

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

wwwroot/additionalStyles.css in the 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 the 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 to the library's stylesheet in the app's <head> markup (location of <head> content):

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). Assign an Assembly collection to the AdditionalAssemblies parameter of the Router component to include the RCL's assembly. 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 {PACKAGE ID} plaatsaanduiding 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. The {PATH AND FILE NAME} placeholder is path and file name under 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 the ComponentLibrary RCL:

Voeg het volgende JeepYJ onderdeel toe aan de RCL.

JeepYJ.razor in the 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 afbeelding van de Jeep YJ® uit de map ComponentLibrary van de wwwroot RCL.
• The JeepYJ component from the 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.
• The {COMPONENT} placeholder is the component.

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 the 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. The first example demonstrates a collocated JS file with an ordinary JS function. 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 onderdelen, die in het tweede voorbeeld aanwezig is, wordt behandeld in ASP.NET Core Razor onderdelenverwijdering.

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 the JsCollocation1 component, the script is referenced at the path of the collocated file. 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 JsCollocation2 methode van het volgende OnAfterRenderAsync 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 the preceding example, JSDisconnectedException is trapped during module disposal in case Blazor's SignalR circuit is lost. 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.

Use of scripts and modules for collocated JS in a Razor class library (RCL) is only supported for Blazor's JS interop mechanism based on the 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 class library (RCL) gebruikmakend van IJSRuntime-gebaseerde JS 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. If a Razor component is located at the root of the RCL, the path segment isn't included.
• 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 Apps that enable Interactive WebAssembly components, Blazor WebAssembly apps, and RCL projects automatically enable browser compatibility checks by adding browser as a supported platform with the 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()
{
    ...
}

For more information, see Annotating APIs as unsupported on specific platforms (dotnet/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.

Runtime relinking trims class instance JavaScript-invokable .NET methods unless they're explicitly preserved. 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
• CSS isolation support with Razor class libraries