Utilizzare ASP.NET componenti di base Razor da una libreria di Razor classi (RCL)

I componenti possono essere condivisi in una libreria di Razor classi (RCL) tra progetti. Includere componenti e asset statici in un'app da:

• Un altro progetto nella soluzione.
• Libreria .NET a cui si fa riferimento.
• Pacchetto NuGet.

Proprio come i componenti sono normali tipi .NET, i componenti forniti da un RCL sono assembly .NET normali.

Creare un RCL

Visual Studio

1. Creare un nuovo progetto.
2. Nella finestra di dialogo Crea un nuovo progetto selezionare Razor Libreria di classi dall'elenco dei modelli di progetto di base di ASP.NET. Selezionare Avanti.
3. Nella finestra di dialogo Configura il nuovo progetto specificare un nome di progetto nel campo Nome progetto. Gli esempi in questo argomento usano il nome ComponentLibrarydel progetto . Selezionare Avanti.
4. Nella finestra di dialogo Informazioni aggiuntive non selezionare Pagine e visualizzazioni di supporto. Seleziona Crea.
5. Aggiungere l'RCL a una soluzione:
   1. Apri la soluzione.
   2. Fare clic con il pulsante destro del mouse sulla soluzione in Esplora soluzioni. Selezionare Aggiungi>progetto esistente.
   3. Passare al file di progetto di RCL.
   4. Selezionare il file di progetto rcl (.csproj).
6. Aggiungere un riferimento all'RCL dall'app:
   1. Fare clic con il pulsante destro del mouse sul progetto dell'app. Selezionare Aggiungi>riferimento al progetto.
   2. Selezionare il progetto RCL. Seleziona OK.

Interfaccia della riga di comando di Visual Studio Code/ .NET

1. Usare il Razor modello di progetto Libreria di classi (razorclasslib) con il dotnet new comando in una shell dei comandi. Nell'esempio seguente viene creato un RCL e denominato ComponentLibrary usando l'opzione -o|--output . La cartella che contiene ComponentLibrary viene creata automaticamente quando viene eseguito il comando:

   dotnet new razorclasslib -o ComponentLibrary
   

2. Per aggiungere la libreria a un progetto esistente, usare il dotnet add reference comando in una shell dei comandi. Nel comando seguente il {PATH TO LIBRARY} segnaposto è il percorso della cartella del progetto della libreria:

   dotnet add reference {PATH TO LIBRARY}
   

Utilizzare un Razor componente da un RCL

Per utilizzare i componenti di un RCL in un altro progetto, usare uno degli approcci seguenti:

• Usare il nome completo del tipo di componente, che include lo spazio dei nomi di RCL.
• I singoli componenti possono essere aggiunti in base al nome senza lo spazio dei nomi della libreria RCL se Razorla direttiva dichiara @using lo spazio dei nomi di RCL. Usare gli approcci seguenti:
  • Aggiungere la @using direttiva ai singoli componenti.
  • includere la @using direttiva nel file di primo livello _Imports.razor per rendere i componenti della libreria disponibili per un intero progetto. Aggiungere la direttiva a un _Imports.razor file a qualsiasi livello per applicare lo spazio dei nomi a un singolo componente o a un set di componenti all'interno di una cartella. Quando si usa un _Imports.razor file, i singoli componenti non richiedono una @using direttiva per lo spazio dei nomi rcl.

Negli esempi seguenti è ComponentLibrary un rcl contenente il Component1 componente. Il Component1 componente è un componente di esempio aggiunto automaticamente a un RCL creato dal modello di progetto RCL che non viene creato per supportare pagine e visualizzazioni.

Component1.razor nell'RCL ComponentLibrary :

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

Nell'app che usa l'RCL fare riferimento al componente usando il Component1 relativo spazio dei nomi, come illustrato nell'esempio seguente.

ConsumeComponent1.razor:

@page "/consume-component-1"

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

<ComponentLibrary.Component1 />

In alternativa, aggiungere una @using direttiva e usare il componente senza il relativo spazio dei nomi. La direttiva seguente @using può essere visualizzata anche in qualsiasi _Imports.razor file in o sopra la cartella corrente.

ConsumeComponent2.razor:

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

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

<Component1 />

Per i componenti della libreria che usano l'isolamento CSS, gli stili dei componenti vengono resi automaticamente disponibili per l'app che usa. Non è necessario collegare manualmente o importare i fogli di stile dei singoli componenti della libreria o il relativo file CSS in bundle nell'app che utilizza la libreria. L'app usa le importazioni CSS per fare riferimento agli stili in bundle di RCL. Gli stili in bundle non vengono pubblicati come asset Web statici dell'app che utilizza la libreria. Per una libreria di classi denominata ClassLib e un'app Blazor con un BlazorSample.styles.css foglio di stile, il foglio di stile dell'RCL viene importato automaticamente nella parte superiore del foglio di stile dell'app in fase di compilazione:

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

Per gli esempi precedenti, Component1il foglio di stile (Component1.razor.css) viene raggruppato automaticamente.

Component1.razor.css nell'RCL ComponentLibrary :

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

L'immagine di sfondo è inclusa anche dal modello di progetto RCL e si trova nella wwwroot cartella dell'RCL.

wwwroot/background.png nell'RCL ComponentLibrary :

Per fornire stili aggiuntivi dei componenti della libreria dai fogli di stile nella cartella della wwwroot libreria, aggiungere tag del foglio <link> di stile al consumer della libreria, come illustrato nell'esempio seguente.

Importante

In genere, i componenti della libreria usano l'isolamento CSS per aggregare e fornire stili di componente. Gli stili dei componenti che si basano sull'isolamento CSS vengono resi automaticamente disponibili per l'app che usa la libreria RCL. Non è necessario collegare manualmente o importare i fogli di stile dei singoli componenti della libreria o il relativo file CSS in bundle nell'app che utilizza la libreria. L'esempio seguente prevede la fornitura di fogli di stile globali all'esterno dell'isolamento CSS, che in genere non è un requisito per le app tipiche che utilizzano gli ELENCHI di classi rcl.

Nell'esempio seguente viene usata l'immagine di sfondo seguente. Se si implementa l'esempio illustrato in questa sezione, fare clic con il pulsante destro del mouse sull'immagine per salvarla in locale.

wwwroot/extra-background.png nell'RCL ComponentLibrary :

Aggiungere un nuovo foglio di stile alla libreria RCL con una extra-style classe .

wwwroot/additionalStyles.css nell'RCL ComponentLibrary :

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

Aggiungere un componente all'RCL che usa la extra-style classe .

ExtraStyles.razor nell'RCL ComponentLibrary :

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

Aggiungere una pagina all'app che usa il ExtraStyles componente dall'RCL.

ConsumeComponent3.razor:

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

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

<ExtraStyles />

Collegamento al foglio di stile della raccolta nel markup dell'app <head> (posizione del <head> contenuto):

Blazor Web Apps:

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

App Blazor WebAssembly autonome:

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

Rendere disponibili i componenti instradabili dall'RCL

Per rendere disponibili componenti instradabili nell'RCL per le richieste dirette, l'assembly rcl deve essere divulgato al router dell'app.

Aprire il componente dell'app App (App.razor). Assegnare una Assembly raccolta al AdditionalAssemblies parametro del Router componente per includere l'assembly rcl. Nell'esempio seguente il ComponentLibrary.Component1 componente viene usato per individuare l'assembly rcl.

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

Per altre informazioni, vedere ASP.NET routing e navigazione coreBlazor.

Creare un RCL con asset statici nella wwwroot cartella

Gli asset statici di un RCL sono disponibili per qualsiasi app che utilizza la libreria.

Inserire gli asset statici nella wwwroot cartella dell'RCL e fare riferimento agli asset statici con il percorso seguente nell'app: _content/{PACKAGE ID}/{PATH AND FILE NAME}. Il segnaposto {PACKAGE ID} è l'ID pacchetto della libreria. Per impostazione predefinita, l'ID pacchetto è il nome dell'assembly del progetto, se <PackageId> non è specificato nel file di progetto. Il {PATH AND FILE NAME} segnaposto è percorso e nome file in wwwroot. Questo formato di percorso viene usato anche nell'app per gli asset statici forniti dai pacchetti NuGet aggiunti alla libreria RCL.

L'esempio seguente illustra l'uso di asset statici RCL con un RCL denominato ComponentLibrary e un'app Blazor che utilizza la libreria RCL. L'app ha un riferimento al progetto per l'RCL ComponentLibrary .

Nell'esempio di questa sezione viene usata l'immagine Jeep® seguente. Se si implementa l'esempio illustrato in questa sezione, fare clic con il pulsante destro del mouse sull'immagine per salvarla in locale.

wwwroot/jeep-yj.png nell'RCL ComponentLibrary :

Aggiungere il componente seguente JeepYJ all'RCL.

JeepYJ.razor nell'RCL ComponentLibrary :

<h3>ComponentLibrary.JeepYJ</h3>

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

Aggiungere il componente seguente Jeep all'app che utilizza l'RCL ComponentLibrary . Il Jeep componente usa:

• Immagine di Jeep YJ® dalla ComponentLibrary cartella della wwwroot RCL.
• Componente JeepYJ dell'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>

Componente sottoposto a Jeep rendering:

Per altre informazioni, vedere Interfaccia utente riutilizzabile Razor nelle librerie di classi con ASP.NET Core.

Creare un rcl con file JavaScript collocati con componenti

La collocazione dei file JavaScript (JS) per Razor i componenti è un modo pratico per organizzare gli script in un'app.

Razor i componenti delle Blazor app collocano JS i file usando l'estensione .razor.js e sono indirizzabili pubblicamente usando il percorso del file nel progetto:

{PATH}/{COMPONENT}.razor.js

• Il {PATH} segnaposto è il percorso del componente.
• Il {COMPONENT} segnaposto è il componente.

Quando l'app viene pubblicata, il framework sposta automaticamente lo script nella radice Web. Gli script vengono spostati in bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.js, dove i segnaposto sono:

• {TARGET FRAMEWORK MONIKER}è il moniker framework di destinazione (TFM).
• {PATH} è il percorso del componente.
• {COMPONENT} è il nome del componente.

Non è necessaria alcuna modifica all'URL relativo dello script, in quanto Blazor si occupa di inserire automaticamente il JS file in asset statici pubblicati.

Questa sezione e gli esempi seguenti sono incentrati principalmente sulla spiegazione della collocazione JS dei file. Il primo esempio illustra un file collocato JS con una funzione comune JS . Il secondo esempio illustra l'uso di un modulo per caricare una funzione, che è l'approccio consigliato per la maggior parte delle app di produzione. La chiamata JS da .NET è descritta in Chiamare le funzioni JavaScript dai metodi .NET in ASP.NET Core Blazor, dove sono disponibili altre spiegazioni dell'API BlazorJS con altri esempi. L'eliminazione dei componenti, presente nel secondo esempio, è descritta in ASP.NET ciclo di vita del componente CoreRazor.

Il componente seguente JsCollocation1 carica uno script tramite un HeadContent componente e chiama una JS funzione con IJSRuntime.InvokeAsync. Il {PATH} segnaposto è il percorso del componente.

Importante

Se si usa il codice seguente per una dimostrazione in un'app di test, modificare il {PATH} segnaposto nel percorso del componente , ad esempio Components/Pages in .NET 8 o versione successiva o Pages in .NET 7 o versioni precedenti. In ( Blazor Web App .NET 8 o versione successiva), il componente richiede una modalità di rendering interattiva applicata a livello globale all'app o alla definizione del componente.

Aggiungere lo script seguente dopo lo Blazor script (percorso dello Blazor script iniziale):

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

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

Il file collocato JS viene posizionato accanto al file del JsCollocation1 componente con il nome JsCollocation1.razor.jsdel file . JsCollocation1 Nel componente viene fatto riferimento allo script nel percorso del file collocato. Nell'esempio seguente la showPrompt1 funzione accetta il nome dell'utente da un Window prompt() oggetto e la restituisce al componente per la JsCollocation1 visualizzazione.

{PATH}/JsCollocation1.razor.js:

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

L'approccio precedente non è consigliato per l'uso generale nelle app di produzione perché l'approccio inquina il client con funzioni globali. Un approccio migliore per le app di produzione consiste nell'usare JS i moduli. Gli stessi principi generali si applicano al caricamento di un JS modulo da un file collocato JS , come illustrato nell'esempio seguente.

Il metodo del componente seguente JsCollocation2 carica un JS modulo in module, che è un IJSObjectReference elemento della classe OnAfterRenderAsync componente. module viene usato per chiamare la showPrompt2 funzione . Il {PATH} segnaposto è il percorso del componente.

Importante

Se si usa il codice seguente per una dimostrazione in un'app di test, modificare il {PATH} segnaposto nel percorso del componente. In ( Blazor Web App .NET 8 o versione successiva), il componente richiede una modalità di rendering interattiva applicata a livello globale all'app o alla definizione del componente.

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

Nell'esempio precedente, JSDisconnectedException viene intrappolato durante l'eliminazione del modulo nel caso Blazorin cui il circuito venga SignalR perso. Se il codice precedente viene usato in un'appBlazor WebAssembly, non c'è alcuna SignalR connessione da perdere, quindi è possibile rimuovere ilcatch try-blocco e lasciare la riga che elimina il modulo ().await module.DisposeAsync(); Per altre informazioni, vedere ASP.NET Core JavaScript interoperabilità (interoperabilità).For more information, see ASP.NET Core Blazor JavaScript interoperability (JS interop).

{PATH}/JsCollocation2.razor.js:

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

L'uso di script e moduli per la collocazione JS in una Razor libreria di classi (RCL) è supportato solo per Blazoril meccanismo di JS interoperabilità basato sull'interfaccia IJSRuntime . Se si implementa l'interoperabilità JavaScript, vedere Interoperabilità JAVAScript [JSImport][JSExport]/JSImport/JSExport con ASP.NET Core.Blazor

Per gli script o i moduli forniti da una Razor libreria di classi (RCL) usando IJSRuntimel'interoperabilità basata su JS , viene usato il percorso seguente:

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

• Il segmento di percorso per la directory corrente (./) è necessario per creare il percorso dell'asset statico corretto del file JS.
• Il segnaposto {PACKAGE ID} è l'identificatore del pacchetto della libreria RCL (o il nome della libreria per una libreria di classi a cui fa riferimento l'app).
• Il {PATH} segnaposto è il percorso del componente. Se un componente Razor si trova nella radice della libreria RCL, il segmento di percorso non è incluso.
• Il {COMPONENT} segnaposto è il nome del componente.
• Il {EXTENSION} segnaposto corrisponde all'estensione del componente, razor o cshtml.

Nell'esempio di app Blazor seguente:

• L'identificatore del pacchetto della libreria RCL è AppJS.
• Gli script di un modulo vengono caricati per il componente JsCollocation3 (JsCollocation3.razor).
• Il componente JsCollocation3 si trova nella cartella Components/Pages della libreria RCL.

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

Analizzatore della compatibilità del browser sul lato client

Le app sul lato client hanno come destinazione l'area di attacco completa dell'API .NET, ma non tutte le API .NET sono supportate in WebAssembly a causa di vincoli sandbox del browser. Le API non supportate generano un'eccezione PlatformNotSupportedException durante l'esecuzione in WebAssembly. Un analizzatore di compatibilità della piattaforma avvisa lo sviluppatore quando l'app usa API non supportate dalle piattaforme di destinazione dell'app. Per le app lato client, ciò significa verificare che le API siano supportate nei browser. L'annotazione delle API .NET Framework per l'analizzatore di compatibilità è un processo in corso, quindi non tutte le API .NET Framework sono attualmente annotate.

Blazor Web Apps che abilitano i componenti, Blazor WebAssembly le app e i progetti RCL interattivi abilitano automaticamente i controlli di compatibilità del browser aggiungendo browser come piattaforma supportata con l'elemento SupportedPlatform MSBuild. Gli sviluppatori di librerie possono aggiungere manualmente l'elemento SupportedPlatform al file di progetto di una libreria per abilitare la funzionalità:

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

Quando si crea una libreria, indicare che una particolare API non è supportata nei browser specificando browser :UnsupportedOSPlatformAttribute

using System.Runtime.Versioning;

...

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

Per altre informazioni, vedere Annotazione di API non supportate in piattaforme specifiche (dotnet/designs repository GitHub).

Isolamento di JavaScript nei moduli di JavaScript

Blazorabilita l'isolamento JavaScript nei moduli JavaScript standard. L'isolamento JavaScript offre i vantaggi seguenti:

• JavaScript importato non inquina più lo spazio dei nomi globale.
• I consumer della libreria e dei componenti non devono importare manualmente il codice JavaScript correlato.

Per altre informazioni, vedere Chiamare funzioni JavaScript da metodi .NET in ASP.NET Core Blazor.

Evitare di tagliare i metodi JavaScript-invokable .NET

Il ricollegamento del runtime taglia i metodi JavaScript-invokable dell'istanza della classe JavaScript, a meno che non vengano mantenuti in modo esplicito. Per altre informazioni, vedere Chiamare metodi .NET da funzioni JavaScript in ASP.NET Core Blazor.

Compilare, comprimere e spedire a NuGet

Poiché Razor le librerie di classi che contengono Razor componenti sono librerie .NET standard, la compressione e la spedizione a NuGet non sono diverse dalla compressione e dalla spedizione di qualsiasi libreria a NuGet. La compressione viene eseguita usando il dotnet pack comando in una shell dei comandi:

dotnet pack

Caricare il pacchetto in NuGet usando il dotnet nuget push comando in una shell dei comandi.

Marchi

Jeep e Jeep YJ sono marchi registrati di FCA US LLC (Stellantis NV).

Risorse aggiuntive

• Interfaccia utente Razor riutilizzabile nelle librerie di classi con ASP.NET Core
• Usare ASP.NET API Core in una libreria di classi
• Aggiungere un file di configurazione trimmer XML Intermediate Language (IL) a una libreria
• Supporto dell'isolamento CSS con Razor librerie di classi