Korzystanie z składników ASP.NET Core Razor z Razor biblioteki klas (RCL)

Składniki można udostępniać w bibliotece klas (RCL) w Razor projektach. Uwzględnij składniki i zasoby statyczne w aplikacji z:

• Inny projekt w rozwiązaniu.
• Przywołyną bibliotekę .NET.
• Pakiet NuGet.

Podobnie jak składniki są zwykłymi typami platformy .NET, składniki dostarczane przez listę RCL są normalnymi zestawami platformy .NET.

Tworzenie listy RCL

Program Visual Studio

1. Tworzenie nowego projektu.
2. W oknie dialogowym Tworzenie nowego projektu wybierz pozycję Razor Biblioteka klas z listy szablonów projektów ASP.NET Core. Wybierz Dalej.
3. W oknie dialogowym Konfigurowanie nowego projektu podaj nazwę projektu w polu Nazwa projektu. Przykłady w tym temacie używają nazwy ComponentLibraryprojektu . Wybierz Dalej.
4. W oknie dialogowym Dodatkowe informacje nie wybieraj stron i widoków pomocy technicznej. Wybierz pozycję Utwórz.
5. Dodaj listę RCL do rozwiązania:
   1. Otwórz rozwiązanie.
   2. Kliknij rozwiązanie prawym przyciskiem myszy w Eksplorator rozwiązań. Wybierz pozycję Dodaj>istniejący projekt.
   3. Przejdź do pliku projektu listy RCL.
   4. Wybierz plik projektu listy RCL (.csproj).
6. Dodaj odwołanie do listy RCL z aplikacji:
   1. Kliknij prawym przyciskiem myszy projekt aplikacji. Wybierz pozycję Dodaj>odwołanie do projektu.
   2. Wybierz projekt listy RCL. Wybierz przycisk OK.

Visual Studio Code/interfejs wiersza polecenia platformy .NET

1. Razor Użyj szablonu projektu Biblioteka klas (razorclasslib) z dotnet new poleceniem w powłoce poleceń. W poniższym przykładzie zostanie utworzona lista RCL i nazwana ComponentLibrary -o|--output przy użyciu opcji . Folder, który przechowuje ComponentLibrary , jest tworzony automatycznie po wykonaniu polecenia:

   dotnet new razorclasslib -o ComponentLibrary
   

2. Aby dodać bibliotekę do istniejącego projektu, użyj dotnet add reference polecenia w powłoce poleceń. W poniższym poleceniu {PATH TO LIBRARY} symbol zastępczy jest ścieżką do folderu projektu biblioteki:

   dotnet add reference {PATH TO LIBRARY}
   

Korzystanie ze Razor składnika z listy RCL

Aby korzystać ze składników z listy RCL w innym projekcie, użyj jednej z następujących metod:

• Użyj pełnej nazwy typu składnika, która zawiera przestrzeń nazw listy RCL.
• Poszczególne składniki można dodać według nazwy bez przestrzeni nazw listy RCL, jeśli Razordyrektywa deklaruje @using przestrzeń nazw listy RCL. Użyj następujących metod:
  • Dodaj dyrektywę @using do poszczególnych składników.
  • uwzględnij dyrektywę @using w pliku najwyższego poziomu _Imports.razor , aby udostępnić składniki biblioteki całemu projektowi. Dodaj dyrektywę _Imports.razor do pliku na dowolnym poziomie, aby zastosować przestrzeń nazw do pojedynczego składnika lub zestawu składników w folderze. _Imports.razor Gdy plik jest używany, poszczególne składniki nie wymagają @using dyrektywy dla przestrzeni nazw listy RCL.

W poniższych przykładach ComponentLibrary jest lista RCL zawierająca Component1 składnik. Składnik Component1 jest przykładowym składnikiem automatycznie dodawanym do listy RCL utworzonej na podstawie szablonu projektu listy RCL, który nie jest tworzony w celu obsługi stron i widoków.

Component1.razor na liście RCL ComponentLibrary :

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

W aplikacji, która korzysta z listy RCL, odwołaj się do Component1 składnika przy użyciu jej przestrzeni nazw, jak pokazano w poniższym przykładzie.

ConsumeComponent1.razor:

@page "/consume-component-1"

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

<ComponentLibrary.Component1 />

Alternatywnie dodaj dyrektywę @using i użyj składnika bez jej przestrzeni nazw. Poniższa @using dyrektywa może również pojawić się w dowolnym _Imports.razor pliku w bieżącym folderze lub powyżej niego.

ConsumeComponent2.razor:

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

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

<Component1 />

W przypadku składników biblioteki korzystających z izolacji CSS style składników są automatycznie udostępniane aplikacji zużywanej. Nie ma potrzeby ręcznego łączenia ani importowania pojedynczych arkuszy stylów składników biblioteki ani powiązanego pliku CSS w aplikacji korzystającej z biblioteki. Aplikacja używa importów CSS do odwołowania się do powiązanych stylów listy RCL. Powiązane style nie są publikowane jako statyczny zasób internetowy aplikacji, która korzysta z biblioteki. W przypadku biblioteki klas o nazwie ClassLib i Blazor aplikacji z arkuszem BlazorSample.styles.css stylów arkusz stylów listy RCL jest importowany w górnej części arkusza stylów aplikacji automatycznie w czasie kompilacji:

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

W poprzednich przykładach Component1arkusz stylów (Component1.razor.css) jest automatycznie pakowany.

Component1.razor.css na liście RCL ComponentLibrary :

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

Obraz tła jest również dołączany z szablonu projektu listy RCL i znajduje się w wwwroot folderze listy RCL.

wwwroot/background.png na liście RCL ComponentLibrary :

Aby zapewnić dodatkowe style składników biblioteki z arkuszy stylów w folderze biblioteki wwwroot , dodaj tagi arkusza <link> stylów do odbiorcy listy RCL, jak pokazano w następnym przykładzie.

Ważne

Ogólnie rzecz biorąc, składniki biblioteki używają izolacji CSS do tworzenia pakietów i udostępniania stylów składników. Style składników, które opierają się na izolacji CSS, są automatycznie udostępniane aplikacji korzystającej z listy RCL. Nie ma potrzeby ręcznego łączenia ani importowania pojedynczych arkuszy stylów składników biblioteki ani powiązanego pliku CSS w aplikacji korzystającej z biblioteki. Poniższy przykład dotyczy udostępniania globalnych arkuszy stylów poza izolacją CSS, co zwykle nie jest wymaganiem dla typowych aplikacji korzystających z list RCLs.

Poniższy obraz tła jest używany w następnym przykładzie. Jeśli zaimplementujesz przykład pokazany w tej sekcji, kliknij prawym przyciskiem myszy obraz, aby zapisać go lokalnie.

wwwroot/extra-background.png na liście RCL ComponentLibrary :

Dodaj nowy arkusz stylów do listy RCL z klasą extra-style .

wwwroot/additionalStyles.css na liście RCL ComponentLibrary :

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

Dodaj składnik do listy RCL, która używa extra-style klasy .

ExtraStyles.razor na liście RCL ComponentLibrary :

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

Dodaj stronę do aplikacji, która używa ExtraStyles składnika z listy RCL.

ConsumeComponent3.razor:

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

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

<ExtraStyles />

Link do arkusza stylów biblioteki w znacznikach aplikacji <head> (lokalizacja <head> zawartości):

Blazor Web Apps:

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

Autonomiczne aplikacje zestawu Blazor WebAssembly:

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

Udostępnianie składników routingu z listy RCL

Aby udostępnić składniki routingu na liście RCL dla żądań bezpośrednich, zestaw listy RCL musi zostać ujawniony routerowi aplikacji.

Otwórz składnik aplikacji App (App.razor). Assembly Przypisz kolekcję do AdditionalAssemblies parametru Router składnika, aby uwzględnić zestaw listy RCL. W poniższym przykładzie ComponentLibrary.Component1 składnik jest używany do odnajdywania zestawu listy RCL.

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

Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor routing i nawigacja.

Tworzenie listy RCL ze statycznymi elementami zawartości w folderze wwwroot

Statyczne zasoby listy RCL są dostępne dla dowolnej aplikacji, która korzysta z biblioteki.

Umieść statyczne zasoby w wwwroot folderze listy RCL i odwołuj się do zasobów statycznych przy użyciu następującej ścieżki w aplikacji: _content/{PACKAGE ID}/{PATH AND FILE NAME}. Symbol zastępczy {PACKAGE ID} to identyfikator pakietu biblioteki. Identyfikator pakietu domyślnie określa nazwę zestawu projektu, jeśli tag <PackageId> nie jest określony w pliku projektu. Symbol {PATH AND FILE NAME} zastępczy to ścieżka i nazwa pliku w obszarze wwwroot. Ten format ścieżki jest również używany w aplikacji dla zasobów statycznych dostarczanych przez pakiety NuGet dodane do listy RCL.

W poniższym przykładzie pokazano użycie statycznych zasobów listy RCL z listą RCL o nazwie ComponentLibrary i aplikacją korzystającą Blazor z listy RCL. Aplikacja ma odwołanie do projektu dla listy ComponentLibrary RCL.

Poniższy obraz jeepu® jest używany w tym przykładzie. Jeśli zaimplementujesz przykład pokazany w tej sekcji, kliknij prawym przyciskiem myszy obraz, aby zapisać go lokalnie.

wwwroot/jeep-yj.png na liście RCL ComponentLibrary :

Dodaj następujący JeepYJ składnik do listy RCL.

JeepYJ.razor na liście RCL ComponentLibrary :

<h3>ComponentLibrary.JeepYJ</h3>

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

Dodaj następujący Jeep składnik do aplikacji, która korzysta z listy ComponentLibrary RCL. Składnik Jeep używa:

• Obraz Jeep YJ® z ComponentLibrary folderu listy RCL wwwroot .
• Składnik JeepYJ z listy 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>

Składnik renderowany Jeep :

Aby uzyskać więcej informacji, zobacz Interfejs użytkownika wielokrotnego użytku Razor w bibliotekach klas z ASP.NET Core.

Tworzenie listy RCL z plikami JavaScript posadzone ze składnikami

Kolokacja plików JavaScript (JS) dla Razor składników to wygodny sposób organizowania skryptów w aplikacji.

RazorBlazor składniki aplikacji składają JS pliki przy użyciu .razor.js rozszerzenia i są publicznie dostępne przy użyciu ścieżki do pliku w projekcie:

{PATH}/{COMPONENT}.razor.js

• Symbol {PATH} zastępczy to ścieżka do składnika.
• Symbol {COMPONENT} zastępczy jest składnikiem.

Po opublikowaniu aplikacji struktura automatycznie przenosi skrypt do katalogu głównego sieci Web. Skrypty są przenoszone do bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.jsobiektu , gdzie symbole zastępcze to:

• {TARGET FRAMEWORK MONIKER} to target framework Moniker (TFM).
• {PATH} to ścieżka do składnika.
• {COMPONENT} to nazwa składnika.

Nie trzeba zmieniać względnego adresu URL skryptu, ponieważ Blazor dba o umieszczenie JS pliku w opublikowanych zasobach statycznych.

W tej sekcji i poniższych przykładach skupiono się głównie na objaśnieniu JS kolokacji pliku. W pierwszym przykładzie pokazano poskładany JS plik ze zwykłą JS funkcją. W drugim przykładzie pokazano użycie modułu do załadowania funkcji, co jest zalecanym podejściem dla większości aplikacji produkcyjnych. Wywoływanie JS z platformy .NET jest w pełni omówione w temacie Wywoływanie funkcji JavaScript z metod platformy .NET w programie ASP.NET CoreBlazor, gdzie istnieją dalsze wyjaśnienia interfejsu BlazorJS API z dodatkowymi przykładami. Usuwanie składników, które znajduje się w drugim przykładzie, jest objęte cyklem życia składników ASP.NET CoreRazor.

Poniższy JsCollocation1 składnik ładuje skrypt za pośrednictwem składnika i wywołuje JS funkcję za pomocą HeadContent IJSRuntime.InvokeAsyncpolecenia . Symbol {PATH} zastępczy to ścieżka do składnika.

Ważne

Jeśli używasz następującego kodu do pokazu w aplikacji testowej, zmień {PATH} symbol zastępczy na ścieżkę składnika (na przykład Components/Pages w programie .NET 8 lub nowszym lub Pages na platformie .NET 7 lub starszej). W programie Blazor Web App (.NET 8 lub nowszym) składnik wymaga interaktywnego trybu renderowania stosowanego globalnie do aplikacji lub definicji składnika.

Dodaj następujący skrypt po Blazor skryscie (lokalizacja skryptu uruchamianiaBlazor):

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

JsCollocation1 component ({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 void ShowPrompt()
    {
        result = await JS.InvokeAsync<string>(
            "showPrompt1", "What's your name?");
        StateHasChanged();
    }
}

Skomponowany plik jest umieszczany JS obok JsCollocation1 pliku składnika o nazwie JsCollocation1.razor.js. W składniku JsCollocation1 skrypt jest przywoływane w ścieżce posadzonego pliku. W poniższym przykładzie showPrompt1 funkcja akceptuje nazwę użytkownika z obiektu Window prompt() i zwraca ją do składnika do wyświetlania JsCollocation1 .

{PATH}/JsCollocation1.razor.js:

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

Powyższe podejście nie jest zalecane do użytku ogólnego w aplikacjach produkcyjnych, ponieważ podejście zanieczyszcza klienta za pomocą funkcji globalnych. Lepszym podejściem dla aplikacji produkcyjnych jest użycie JS modułów. Te same ogólne zasady dotyczą ładowania modułu JS ze s collocated JS pliku, jak pokazano w następnym przykładzie.

Metoda następującego składnika ładuje JS moduł do moduleklasy , która jest klasą IJSObjectReference składników.OnAfterRenderAsync JsCollocation2 module służy do wywoływania showPrompt2 funkcji. Symbol {PATH} zastępczy to ścieżka do składnika.

Ważne

Jeśli używasz następującego kodu do pokazu w aplikacji testowej, zmień {PATH} symbol zastępczy na ścieżkę składnika. W programie Blazor Web App (.NET 8 lub nowszym) składnik wymaga interaktywnego trybu renderowania stosowanego globalnie do aplikacji lub definicji składnika.

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

W poprzednim przykładzie JSDisconnectedException jest uwięziony podczas usuwania modułu w przypadku Blazorutraty obwodu SignalR . Jeśli poprzedni kod jest używany w Blazor WebAssembly aplikacji, nie ma SignalR połączenia do utraty, więc możesz usunąćcatch try-blok i pozostawić wiersz, który usuwa moduł ().await module.DisposeAsync(); Aby uzyskać więcej informacji, zobacz ASP.NET Core Blazor JavaScript interoperability (JS interop).

{PATH}/JsCollocation2.razor.js:

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

Używanie skryptów i modułów do sortowania JS w bibliotece klas (RCL) jest obsługiwane tylko dla BlazorJS mechanizmu międzyoperacyjności opartego na interfejsie IJSRuntime Razor. Jeśli wdrażasz międzyoperację języka JavaScript[JSExport]/[JSImport], zobacz Międzyoperacja javaScript JSImport/JSExport z ASP.NET Core.Blazor

W przypadku skryptów lub modułów udostępnianych przez bibliotekę Razor klas (RCL) przy użyciu IJSRuntimemiędzyoperacyjności opartej na JS technologii jest używana następująca ścieżka:

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

• Segment ścieżki dla bieżącego katalogu (./) jest wymagany w celu utworzenia poprawnej statycznej ścieżki zasobów do pliku JS.
• Symbol zastępczy {PACKAGE ID} to identyfikator pakietu biblioteki RCL (lub nazwa biblioteki dla biblioteki klas, do której odwołuje się aplikacja).
• Symbol {PATH} zastępczy to ścieżka do składnika. Jeśli składnik Razor znajduje się w katalogu głównym biblioteki RCL, segment ścieżki nie jest uwzględniany.
• Symbol {COMPONENT} zastępczy to nazwa składnika.
• Symbol {EXTENSION} zastępczy pasuje do rozszerzenia składnika lub razor cshtml.

W poniższym przykładzie aplikacji platformy Blazor:

• Identyfikator pakietu biblioteki RCL to AppJS.
• Skrypty modułu są ładowane dla składnika JsCollocation3 (JsCollocation3.razor).
• Składnik JsCollocation3 znajduje się w folderze Components/Pages biblioteki RCL.

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

Analizator zgodności przeglądarki po stronie klienta

Aplikacje po stronie klienta dotyczą pełnego obszaru powierzchni interfejsu API platformy .NET, ale nie wszystkie interfejsy API platformy .NET są obsługiwane w zestawie WebAssembly z powodu ograniczeń piaskownicy przeglądarki. Nieobsługiwane interfejsy API zgłaszane PlatformNotSupportedException podczas uruchamiania w zestawie WebAssembly. Analizator zgodności platformy ostrzega dewelopera, gdy aplikacja korzysta z interfejsów API, które nie są obsługiwane przez platformy docelowe aplikacji. W przypadku aplikacji po stronie klienta oznacza to, że interfejsy API są obsługiwane w przeglądarkach. Dodawanie adnotacji do interfejsów API platformy .NET Framework dla analizatora zgodności jest procesem, więc nie wszystkie interfejsy API platformy .NET Framework są obecnie oznaczone adnotacjami.

Blazor Web Apps, które umożliwiają automatyczne sprawdzanie zgodności interakcyjne składniki, Blazor WebAssembly aplikacje i listy RCL interakcyjnych składników WebAssembly, dodając browser jako obsługiwaną platformę z SupportedPlatform elementem MSBuild. Deweloperzy bibliotek mogą ręcznie dodać SupportedPlatform element do pliku projektu biblioteki, aby włączyć tę funkcję:

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

Podczas tworzenia biblioteki wskaż, że określony interfejs API nie jest obsługiwany w przeglądarkach, określając wartość browser :UnsupportedOSPlatformAttribute

using System.Runtime.Versioning;

...

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

Aby uzyskać więcej informacji, zobacz Dodawanie adnotacji do interfejsów API jako nieobsługiwanych na określonych platformach (dotnet/designs repozytorium GitHub).

Izolacja języka JavaScript w modułach języka JavaScript

Blazor umożliwia izolację języka JavaScript w standardowych modułach Języka JavaScript. Izolacja w języku JavaScript zapewnia następujące korzyści:

• Zaimportowany kod JavaScript nie zanieczyszcza już globalnej przestrzeni nazw.
• Użytkownicy biblioteki i składników nie muszą ręcznie importować powiązanego kodu JavaScript.

Aby uzyskać więcej informacji, zobacz Wywoływanie funkcji języka JavaScript z metod platformy .NET na platformie ASP.NET Core Blazor.

Unikaj przycinania metod javaScript-invokable .NET

Ponowne łączenie środowiska uruchomieniowego powoduje przycinanie wystąpień klasy JavaScript wywoływanych przez platformę .NET, chyba że zostaną jawnie zachowane. Aby uzyskać więcej informacji, zobacz Wywoływanie metod platformy .NET z funkcji Języka JavaScript w programie ASP.NET Core Blazor.

Kompilowanie, pakowanie i dostarczanie do narzędzia NuGet

Ponieważ Razor biblioteki klas zawierające Razor składniki są standardowymi bibliotekami platformy .NET, pakowanie i wysyłanie ich do pakietu NuGet nie różni się od pakowania i wysyłania dowolnej biblioteki do pakietu NuGet. Pakowanie odbywa się przy użyciu dotnet pack polecenia w powłoce poleceń:

dotnet pack

Przekaż pakiet do pakietu NuGet przy użyciu dotnet nuget push polecenia w powłoce poleceń.

Znaki towarowe

Jeep i Jeep YJ są zastrzeżonymi znakami towarowymi FCA US LLC (Stellantis NV).

Dodatkowe zasoby

• Interfejs użytkownika Razor do ponownego wykorzystania w bibliotekach klas na platformie ASP.NET Core
• Używanie interfejsów API ASP.NET Core w bibliotece klas
• Dodawanie pliku konfiguracji trimmer języka XML Intermediate Language (IL) do biblioteki
• Obsługa izolacji CSS z bibliotekami Razor klas