Usare LibMan con ASP.NET Core in Visual Studio

Articolo
11/30/2023

Di Scott Addie

Visual Studio include il supporto predefinito per LibMan nei progetti ASP.NET Core, tra cui:

Supporto per la configurazione e l'esecuzione di operazioni di ripristino libMan per la compilazione.
Voci di menu per attivare le operazioni di ripristino e pulizia di LibMan.
Finestra di dialogo di ricerca per trovare librerie e aggiungere i file a un progetto.
Supporto per la modifica di libman.json, ovvero il file manifesto LibMan.

Visualizzare o scaricare il codice di esempio (come scaricare)

Prerequisiti

Visual Studio 2019 con il carico di lavoro Sviluppo ASP.NET e Web

Aggiungere file di libreria

I file di libreria possono essere aggiunti a un progetto ASP.NET Core in due modi diversi:

Usare la finestra di dialogo Aggiungi libreria lato client
Configurare manualmente le voci del file manifesto LibMan

Usare la finestra di dialogo Aggiungi libreria lato client

Per installare una libreria lato client, seguire questa procedura:

In Esplora soluzioni fare clic con il pulsante destro del mouse sulla cartella del progetto in cui aggiungere i file. Scegliere Aggiungi>libreria lato client. Viene visualizzata la finestra di dialogo Aggiungi libreria lato client:
Selezionare il provider di libreria dall'elenco a discesa Provider . JS rete CDN è il provider predefinito.
Digitare il nome della libreria da recuperare nella casella di testo Libreria . IntelliSense fornisce un elenco di librerie che iniziano con il testo fornito.
Selezionare la libreria dall'elenco IntelliSense. Si noti che il nome della libreria è suffisso con il @ simbolo e la versione stabile più recente nota al provider selezionato.
Decidere quali file includere:
- Selezionare il pulsante di opzione Includi tutti i file di libreria per includere tutti i file della libreria.
- Selezionare il pulsante di opzione Scegli file specifici per includere un subset dei file della libreria. Quando si seleziona il pulsante di opzione, l'albero del selettore di file è abilitato. Selezionare le caselle a sinistra dei nomi di file da scaricare.

Specificare la cartella del progetto per archiviare i file nella casella di testo Percorso di destinazione. Come raccomandazione, archiviare ogni libreria in una cartella separata.

La cartella Percorso di destinazione suggerita si basa sul percorso da cui è stata avviata la finestra di dialogo:

Se avviato dalla radice del progetto:
- wwwroot/lib viene usato se wwwroot esiste.
- lib viene usato se wwwroot non esiste.
Se avviato da una cartella di progetto, viene usato il nome della cartella corrispondente.

Il suggerimento della cartella è suffisso con il nome della libreria. Nella tabella seguente vengono illustrati i suggerimenti per le cartelle durante l'installazione di jQuery in un Razor progetto Pages.

Posizione di avvio	Cartella suggerita
radice del progetto (se wwwroot esiste)	wwwroot/lib/jquery/
radice del progetto (se wwwroot non esiste)	lib/jquery/
Cartella Pages nel progetto	Pages/jquery/

Fare clic sul pulsante Installa per scaricare i file, in base alla configurazione in libman.json.

Esaminare il feed gestione librerie della finestra Output per informazioni dettagliate sull'installazione. Ad esempio:

Restore operation started...
Restoring libraries for project LibManSample
Restoring library jquery@3.3.1... (LibManSample)
wwwroot/lib/jquery/jquery.min.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.min.map written to destination (LibManSample)
Restore operation completed
1 libraries restored in 2.32 seconds

Configurare manualmente le voci del file manifesto LibMan

Tutte le operazioni LibMan in Visual Studio si basano sul contenuto del manifesto LibMan della radice del progetto (libman.json). È possibile modificare libman.json manualmente per configurare i file di libreria per il progetto. Visual Studio ripristina tutti i file di libreria una volta libman.json salvati.

Per aprire libman.json per la modifica, sono disponibili le opzioni seguenti:

Fare doppio clic sul libman.json file in Esplora soluzioni.
Fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni e scegliere Gestisci librerie lato client. †
Selezionare Gestisci librerie lato client dal menu Progetto di Visual Studio. †

† Se il libman.json file non esiste già nella radice del progetto, verrà creato con il contenuto del modello di elemento predefinito.

Visual Studio offre supporto avanzato JSper la modifica ON, ad esempio la colorazione, la formattazione, IntelliSense e la convalida dello schema. Lo schema ON del JSmanifesto LibMan è disponibile in https://json.schemastore.org/libman.

Con il file manifesto seguente, LibMan recupera i file in base alla configurazione definita nella libraries proprietà . Una spiegazione dei valori letterali oggetto definiti all'interno libraries di quanto segue:

Un subset di jQuery versione 3.3.1 viene recuperato dal provider di rete CDNJS. Il subset è definito nella files proprietàjquery.min.js , jquery.jse jquery.min.map. I file vengono inseriti nella cartella wwwroot/lib/jquery del progetto.
L'intera versione di Bootstrap 4.1.3 viene recuperata e inserita in una cartella wwwroot/lib/bootstrap . La proprietà del valore letterale dell'oggetto provider esegue l'override del valore della defaultProvider proprietà. LibMan recupera i file bootstrap dal provider unpkg.
Un subset di Lodash è stato approvato da un organo di governance all'interno dell'organizzazione. I lodash.js file e lodash.min.js vengono recuperati dal file system locale in C:\temp\lodash\. I file vengono copiati nella cartella wwwroot/lib/lodash del progetto.

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "libraries": [
    {
      "library": "jquery@3.3.1",
      "files": [
        "jquery.min.js",
        "jquery.js",
        "jquery.min.map"
      ],
      "destination": "wwwroot/lib/jquery/"
    },
    {
      "provider": "unpkg",
      "library": "bootstrap@4.1.3",
      "destination": "wwwroot/lib/bootstrap/"
    },
    {
      "provider": "filesystem",
      "library": "C:\\temp\\lodash\\",
      "files": [
        "lodash.js",
        "lodash.min.js"
      ],
      "destination": "wwwroot/lib/lodash/"
    }
  ]
}

Nota

LibMan supporta solo una versione di ogni libreria di ogni provider. Il libman.json file non riesce a convalidare lo schema se contiene due librerie con lo stesso nome di libreria per un determinato provider.

Ripristinare i file di libreria

Per ripristinare i file di libreria da Visual Studio, nella radice del progetto deve essere presente un file valido libman.json . I file ripristinati vengono inseriti nel progetto nel percorso specificato per ogni libreria.

I file di libreria possono essere ripristinati in un progetto ASP.NET Core in due modi:

Ripristinare i file durante la compilazione
Ripristinare manualmente i file

Ripristinare i file durante la compilazione

LibMan può ripristinare i file di libreria definiti come parte del processo di compilazione. Per impostazione predefinita, il comportamento di ripristino in fase di compilazione è disabilitato.

Per abilitare e testare il comportamento di ripristino in fase di compilazione:

Fare clic con il pulsante destro del mouse libman.json in Esplora soluzioni e scegliere Abilita ripristina librerie lato client in Compila dal menu di scelta rapida.
Fare clic sul pulsante Sì quando viene richiesto di installare un pacchetto NuGet. Il pacchetto NuGet Microsoft.Web.LibraryManager.Build viene aggiunto al progetto:
```
<PackageReference Include="Microsoft.Web.LibraryManager.Build" Version="1.0.113" />
```
Compilare il progetto per verificare che si verifichi il ripristino del file LibMan. Il Microsoft.Web.LibraryManager.Build pacchetto inserisce una destinazione MSBuild che esegue LibMan durante l'operazione di compilazione del progetto.

Esaminare il feed di compilazione della finestra Output per un log attività LibMan:

1>------ Build started: Project: LibManSample, Configuration: Debug Any CPU ------
1>
1>Restore operation started...
1>Restoring library jquery@3.3.1...
1>Restoring library bootstrap@4.1.3...
1>
1>2 libraries restored in 10.66 seconds
1>LibManSample -> C:\LibManSample\bin\Debug\netcoreapp2.1\LibManSample.dll
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

Quando il comportamento di ripristino in fase di compilazione è abilitato, nel libman.json menu di scelta rapida viene visualizzata un'opzione Disabilita ripristina librerie lato client in compilazione . Se si seleziona questa opzione, il riferimento al Microsoft.Web.LibraryManager.Build pacchetto viene rimosso dal file di progetto. Di conseguenza, le librerie lato client non vengono più ripristinate in ogni compilazione.

Indipendentemente dall'impostazione di ripristino in fase di compilazione, è possibile ripristinare manualmente in qualsiasi momento dal libman.json menu di scelta rapida. Per altre informazioni, vedere Ripristinare manualmente i file.

Ripristinare manualmente i file

Per ripristinare manualmente i file di libreria:

Per tutti i progetti nella soluzione:
- Fare clic con il pulsante destro del mouse sul nome della soluzione in Esplora soluzioni.
- Selezionare l'opzione Ripristina librerie lato client.
Per un progetto specifico:
- Fare clic con il pulsante destro del mouse sul libman.json file in Esplora soluzioni.
- Selezionare l'opzione Ripristina librerie lato client.

Durante l'esecuzione dell'operazione di ripristino:

L'icona del Centro stato attività (TSC) sulla barra di stato di Visual Studio verrà animata e leggerà l'operazione di ripristino avviata. Facendo clic sull'icona viene aperta una descrizione comando che elenca le attività in background note.

I messaggi verranno inviati alla barra di stato e al feed Gestione librerie della finestra Output . Ad esempio:

Restore operation started...
Restoring libraries for project LibManSample
Restoring library jquery@3.3.1... (LibManSample)
wwwroot/lib/jquery/jquery.min.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.js written to destination (LibManSample)
wwwroot/lib/jquery/jquery.min.map written to destination (LibManSample)
Restore operation completed
1 libraries restored in 2.32 seconds

Eliminare i file di libreria

Per eseguire l'operazione di pulizia , che elimina i file di libreria ripristinati in precedenza in Visual Studio:

Fare clic con il pulsante destro del mouse sul libman.json file in Esplora soluzioni.
Selezionare l'opzione Pulisci librerie lato client.

Per impedire la rimozione accidentale di file non di libreria, l'operazione pulita non elimina intere directory. Rimuove solo i file inclusi nel ripristino precedente.

Durante l'esecuzione dell'operazione di pulizia:

L'icona TSC sulla barra di stato di Visual Studio verrà animata e leggerà l'operazione librerie client avviata. Facendo clic sull'icona viene aperta una descrizione comando che elenca le attività in background note.
I messaggi vengono inviati alla barra di stato e al feed Gestione librerie della finestra Output . Ad esempio:

Clean libraries operation started...
Clean libraries operation completed
2 libraries were successfully deleted in 1.91 secs

L'operazione di pulizia elimina solo i file dal progetto. I file di libreria rimangono nella cache per un recupero più rapido in caso di operazioni di ripristino future. Per gestire i file di libreria archiviati nella cache del computer locale, usare l'interfaccia della riga di comando di LibMan.

Disinstallare i file di libreria

Per disinstallare i file di libreria:

libman.json aperti.
Posizionare il cursore all'interno del valore letterale oggetto corrispondente libraries .
Fare clic sull'icona della lampadina visualizzata nel margine sinistro e selezionare Disinstalla <library_name>@<library_version>:

In alternativa, è possibile modificare e salvare manualmente il manifesto LibMan (libman.json). L'operazione di ripristino viene eseguita quando il file viene salvato. I file di libreria non più definiti in libman.json vengono rimossi dal progetto.

Aggiornare la versione della libreria

Per verificare la disponibilità di una versione aggiornata della libreria:

libman.json aperti.
Posizionare il cursore all'interno del valore letterale oggetto corrispondente libraries .
Fare clic sull'icona a forma di lampadina visualizzata nel margine sinistro. Passare il puntatore del mouse su Controlla aggiornamenti.

LibMan verifica la disponibilità di una versione della libreria più recente rispetto alla versione installata. I risultati seguenti possono verificarsi:

Se la versione più recente è già installata, viene visualizzato un messaggio Nessun aggiornamento trovato .
Se non è già installata, viene visualizzata la versione stabile più recente.
Se è disponibile una versione non definitiva rispetto alla versione installata, viene visualizzata la versione non definitiva.

Per effettuare il downgrade a una versione precedente della libreria, modificare manualmente il libman.json file. Quando il file viene salvato, l'operazione di ripristino libMan:

Rimuove i file ridondanti dalla versione precedente.
Aggiunge file nuovi e aggiornati dalla nuova versione.

Condividi tramite