Condividi tramite

Guida introduttiva: Creare e pubblicare un pacchetto NuGet con Visual Studio (solo Windows)

  • Articolo

Con Microsoft Visual Studio è possibile creare un pacchetto NuGet da una libreria di classi .NET e quindi pubblicarlo in nuget.org usando uno strumento dell'interfaccia della riga di comando.

La guida introduttiva è solo per gli utenti di Windows. Se si usa un Mac, si dovrebbe usare l'interfaccia della riga di comando di .NET .

Prerequisiti

  • Installare Visual Studio 2022 per Windows con un carico di lavoro correlato a .NET Core.

    È possibile installare gratuitamente l'edizione Community 2022 da visualstudio.microsoft.comoppure usare Professional o Enterprise Edition.

    Visual Studio 2017 e versioni successive includono automaticamente le funzionalità NuGet quando si installa un carico di lavoro correlato a .NET.

  • Assicurati di installare il .NET CLI, se non è già installato.

    Per Visual Studio 2017 e versioni successive, l'interfaccia della riga di comando di .NET viene installata automaticamente con qualsiasi carico di lavoro correlato a .NET Core. In caso contrario, installare il .NET Core SDK per ottenere la CLI di .NET. L'interfaccia della riga di comando di .NET è necessaria per i progetti .NET che usano il formato SDK stile (attributo SDK). Il modello di libreria di classi .NET predefinito in Visual Studio 2017 e versioni successive usa l'attributo SDK.

    Importante

    Se si usa un progetto non in stile SDK, seguire le procedure in Creare e pubblicare un pacchetto .NET Framework (Visual Studio) invece per creare e pubblicare il pacchetto. Per questo articolo, è consigliabile usare l'interfaccia della riga di comando di .NET. Anche se è possibile pubblicare qualsiasi pacchetto NuGet usando l'interfaccia della riga di comando di NuGet, alcuni dei passaggi descritti in questo articolo sono specifici per i progetti in stile SDK e l'interfaccia della riga di comando di .NET. La CLI di NuGet viene utilizzata per progetti non conformi allo stile SDK (di solito .NET Framework).

  • Registrati per un account gratuito su nuget.org se non ne hai già uno. È necessario registrare e confermare l'account prima di poter caricare un pacchetto NuGet.

  • Installare l'interfaccia della riga di comando di NuGet scaricandola da nuget.org. Aggiungere il file nuget.exe a una cartella appropriata e aggiungere tale cartella alla variabile di ambiente PATH.

Creare un progetto di libreria di classi

È possibile usare un progetto libreria di classi .NET esistente per il codice che si vuole creare nel pacchetto oppure crearne uno come indicato di seguito:

  1. In Visual Studio selezionare File>Nuovo progetto>.

  2. Nella finestra Crea un nuovo progetto selezionare C#, Windowse Library negli elenchi a discesa.

  3. Nell'elenco risultante dei modelli di progetto selezionare libreria di classi (con la descrizione Un progetto per la creazione di una libreria di classi destinata a .NET o .NET Standard) e quindi selezionare Avanti.

  4. Nella finestra Configura il tuo nuovo progetto, immettere AppLogger per il nome progetto, e quindi selezionare Avanti.

  5. Nella finestra Informazioni aggiuntive, seleziona un Framework appropriatoe poi seleziona Crea.

    Se non si è certi del framework da selezionare, la versione più recente è una buona scelta e può essere facilmente modificata in un secondo momento. Per informazioni su quale framework utilizzare, consulta When to target .NET 5.0 or .NET 6.0 vs. .NET Standard.

  6. Per assicurarsi che il progetto sia stato creato correttamente, selezionare Compila>Compila Soluzione. La DLL si trova all'interno della cartella Debug (o Release se si compila tale configurazione).

  7. (Facoltativo) Per questa guida introduttiva non è necessario scrivere codice aggiuntivo per il pacchetto NuGet perché la libreria di classi modello è sufficiente per creare un pacchetto. Tuttavia, se si vuole un codice funzionale per il pacchetto, includere il codice seguente:

    namespace AppLogger
{
    public class Logger
    {
        public void Log(string text)
        {
            Console.WriteLine(text);
        }
    }
}

Configurare le proprietà del pacchetto

Dopo aver creato il progetto, è possibile configurare le proprietà del pacchetto NuGet seguendo questa procedura:

  1. Selezionare il vostro progetto in Esplora soluzionie quindi selezionare Progetto><nome del progetto> Proprietà, dove <nome del progetto> è il nome del vostro progetto.

  2. Espandi il pacchetto nodo, e quindi seleziona Generale.

    Il nodo pacchetto viene visualizzato solo per i progetti in stile SDK in Visual Studio. Se si sta lavorando su un progetto di tipo non SDK (in genere .NET Framework), eseguire la migrazione del progettooppure consultare Creare e pubblicare un pacchetto .NET Framework per istruzioni dettagliate.

    Screenshot che mostra le proprietà del pacchetto NuGet in un progetto di Visual Studio.

  3. Per i pacchetti creati per l'utilizzo pubblico, prestare particolare attenzione alla proprietà dei tag , perché i tag aiutano gli altri a trovare il pacchetto e a capire cosa fa.

  4. Assegna al pacchetto un ID pacchetto univoco e compila le eventuali altre proprietà desiderate. Per una tabella che mostra il mapping delle proprietà di MSBuild (progetti in stile SDK) alle proprietà del file .nuspec, vedere gli obiettivi pack . Per una descrizione delle proprietà del file .nuspec, vedere il riferimento al file .nuspec. Tutte queste proprietà vengono inserite nel manifesto .nuspec creato da Visual Studio per il progetto.

    Importante

    È necessario assegnare al pacchetto un identificatore univoco tra nuget.org o qualsiasi host in uso. In caso contrario, si verifica un errore. Per questa guida rapida è consigliabile includere Esempio o Test nel nome perché il passaggio di pubblicazione rende il pacchetto visibile pubblicamente.

  5. (Facoltativo) Per visualizzare le proprietà direttamente nel file di progetto AppLogger.csproj, selezionare Progetto>Modifica file di progetto.

    Viene caricata la scheda AppLogger.csproj.

    Questa opzione è disponibile a partire da Visual Studio 2017 per i progetti che usano l'attributo in stile SDK. Per le versioni precedenti di Visual Studio, è necessario selezionare Project>Scarica progetto prima di poter modificare il file di progetto.

Eseguire il comando pack

Per creare un pacchetto NuGet dal progetto, seguire questa procedura:

  1. Selezionare Build>Configuration Managere quindi impostare il di configurazione della soluzione active su Release.

  2. Selezionare il progetto AppLogger in Esplora soluzioni , quindi selezionare Pack.

    Visual Studio compila il progetto e crea il file .nupkg.

  3. Esaminare la finestra Output per informazioni dettagliate, che contiene il percorso del file del pacchetto. In questo esempio l'assembly compilato si trova in bin\Release\net6.0 come adatto a una destinazione .NET 6.0:

    1>------ Build started: Project: AppLogger, Configuration: Release Any CPU ------
1>AppLogger -> d:\proj\AppLogger\AppLogger\bin\Release\net6.0\AppLogger.dll
1>Successfully created package 'd:\proj\AppLogger\AppLogger\bin\Release\AppLogger.1.0.0.nupkg'.
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

  4. Se il comando Pack non viene visualizzato nel menu, il progetto probabilmente non è un progetto in stile SDK ed è necessario usare l'interfaccia della riga di comando di NuGet. O eseguire la migrazione del progetto e usare il .NET CLI, oppure consultare Creare e pubblicare un pacchetto .NET Framework per istruzioni passo per passo.

(Facoltativo) Generare un pacchetto alla compilazione

È possibile configurare Visual Studio per generare automaticamente il pacchetto NuGet quando si compila il progetto:

  1. Selezionare il progetto in Esplora soluzioni e quindi selezionare nome progetto><nome progetto> Proprietà, dove <nome del progetto> è il nome del progetto (in questo caso AppLogger).

  2. Espandi il nodo pacchetto, seleziona Generalee quindi seleziona Genera pacchetto NuGet durante la compilazione.

    Screenshot che mostra le proprietà del pacchetto con Selezionata l'opzione di generazione del pacchetto NuGet durante la compilazione.

Nota

Quando si genera automaticamente il pacchetto, il tempo aggiuntivo per il pacchetto aumenta il tempo di compilazione complessivo per il progetto.

(Facoltativo) Esegui il pacchetto con MSBuild

In alternativa all'uso del comando di menu Pack, NuGet 4.x+ e MSBuild 15.1+ supporta una destinazione pack quando il progetto contiene i dati del pacchetto necessari:

  1. Con il progetto aperto in Esplora soluzioni, aprire un prompt dei comandi selezionando strumenti >riga di comando>prompt dei comandi per gli sviluppatori.

    Il prompt dei comandi si apre nella directory del progetto.

  2. Eseguire il comando seguente: msbuild -t:pack.

Per altre informazioni, vedere Creare un pacchetto con MSBuild.

Pubblicare il pacchetto

Dopo aver creato un file .nupkg, pubblicarlo in nuget.org usando l'interfaccia della riga di comando di .NET o l'interfaccia della riga di comando di NuGet, insieme a una chiave API acquisita da nuget.org.

Nota

  • Nuget.org analizza tutti i pacchetti caricati per individuare virus e rifiuta i pacchetti se rileva virus. Nuget.org analizza periodicamente tutti i pacchetti elencati esistenti.

  • I pacchetti pubblicati in nuget.org sono visibili pubblicamente ad altri sviluppatori, a meno che non vengano elencati. Per ospitare i pacchetti privatamente, vedere Ospitare feed NuGet personalizzati.

Acquisire la chiave API

Prima di pubblicare il pacchetto NuGet, creare una chiave API:

  1. Accedere all'account nuget.org o creare un account se non ne è già disponibile uno.

  2. Selezionare il nome utente in alto a destra e quindi selezionare chiavi API .

  3. Selezionare Creae specificare un nome per la chiave.

  4. In Selezionare Ambiti, selezionare Push.

  5. In Selezionare pacchetti>modello Globimmettere *.

  6. Selezionare Crea.

  7. Selezionare Copia per copiare la nuova chiave.

    Screenshot che mostra la nuova chiave API con il collegamento

Importante

  • Mantenere sempre la chiave API un segreto. La chiave API è simile a una password che consente a chiunque di gestire i pacchetti per conto dell'utente. Eliminare o rigenerare la chiave API se viene accidentalmente visualizzata.
  • Salvare la chiave in una posizione sicura, perché non è possibile copiare di nuovo la chiave in un secondo momento. Se si torna alla pagina della chiave API, è necessario rigenerare la chiave per copiarla. È anche possibile rimuovere la chiave API se non si vuole più eseguire il push dei pacchetti.

Definizione dell'ambito consente di creare chiavi API separate per scopi diversi. Ogni chiave ha un intervallo di tempo di scadenza ed è possibile definire l'ambito della chiave a pacchetti o modelli GLOB specifici. È anche possibile definire l'ambito di ogni chiave per operazioni specifiche: eseguire il push di nuovi pacchetti e versioni dei pacchetti, eseguire il push solo di nuove versioni del pacchetto o annullare l'elenco.

Tramite la definizione dell'ambito, è possibile creare chiavi API per persone diverse che gestiscono i pacchetti per l'organizzazione in modo che abbiano solo le autorizzazioni necessarie.

Per altre informazioni, vedere chiavi API con ambito.

Pubblicare con l'interfaccia della riga di comando di .NET o l'interfaccia della riga di comando di NuGet

Ognuno degli strumenti dell'interfaccia della riga di comando seguenti consente di eseguire il push di un pacchetto nel server e di pubblicarlo. Selezionare la scheda per il proprio strumento CLI, CLI .NET o CLI di NuGet.

  • .NET CLI
  • dell'interfaccia della riga di comando di NuGet

L'uso dell'interfaccia della riga di comando di .NET (dotnet.exe) è l'alternativa consigliata all'uso dell'interfaccia della riga di comando di NuGet.

Dalla cartella contenente il file nupkg eseguire il comando seguente. Indicate il nome del file .nupkg e sostituire il valore della chiave con la chiave dell'API.

dotnet nuget push Contoso.08.28.22.001.Test.1.0.0.nupkg --api-key qz2jga8pl3dvn2akksyquwcs9ygggg4exypy3bhxy6w6x6 --source https://api.nuget.org/v3/index.json

L'output mostra i risultati del processo di pubblicazione:

Pushing Contoso.08.28.22.001.Test.1.0.0.nupkg to 'https://www.nuget.org/api/v2/package'...
  PUT https://www.nuget.org/api/v2/package/
warn : All published packages should have license information specified. Learn more: https://aka.ms/nuget/authoring-best-practices#licensing.
  Created https://www.nuget.org/api/v2/package/ 1221ms
Your package was pushed.

Per altre informazioni, vedere dotnet nuget push.

Nota

Se si vuole evitare che il pacchetto di test sia attivo in nuget.org, è possibile eseguire il push nel sito di test nuget.org in https://int.nugettest.org. Si noti che i pacchetti caricati in int.nugettest.org potrebbero non essere mantenuti.

Errori di pubblicazione

Gli errori del comando push indicano in genere il problema. Ad esempio, potrebbe essere stato dimenticato di aggiornare il numero di versione nel progetto, quindi si sta provando a pubblicare un pacchetto già esistente.

Vengono visualizzati anche errori se la chiave API non è valida o scaduta o se si tenta di pubblicare un pacchetto usando un identificatore già esistente nell'host. Si supponga, ad esempio, che l'identificatore AppLogger-test esista già in nuget.org. Se si tenta di pubblicare un pacchetto con tale identificatore, il comando push restituisce l'errore seguente:

Response status code does not indicate success: 403 (The specified API key is invalid,
has expired, or does not have permission to access the specified package.).

Se viene visualizzato questo errore, verificare di usare una chiave API valida che non è scaduta. In caso affermativo, l'errore indica che l'identificatore del pacchetto esiste già nell'host. Per correggere l'errore, modificare l'identificatore del pacchetto in modo che sia univoco, ricompilare il progetto, ricreare il file .nupkg e ripetere il comando push.

Gestire il pacchetto pubblicato

Quando il pacchetto viene pubblicato correttamente, si riceve un messaggio di posta elettronica di conferma. Per vedere il pacchetto appena pubblicato, su nuget.orgselezionare il proprio nome utente nell'angolo in alto a destra e poi selezionare Gestisci pacchetti.

Nota

L'indicizzazione e la visualizzazione del pacchetto nei risultati della ricerca in cui altri utenti possono trovarli potrebbero richiedere un po' di tempo. Durante tale periodo, il pacchetto viene visualizzato in Pacchetti non elencatie la pagina del pacchetto mostra il messaggio seguente:

Screenshot che mostra il messaggio di pubblicazione visualizzato quando si carica un pacchetto in nuget.org.

A questo punto è stato pubblicato un pacchetto NuGet per nuget.org che altri sviluppatori possono usare nei progetti.

Se è stato creato un pacchetto che non è utile ,ad esempio questo pacchetto di esempio creato con una libreria di classi vuota, oppure si decide di non voler visualizzare il pacchetto, è possibile annullare l'elenco il pacchetto per nasconderlo dai risultati della ricerca:

  1. Dopo che il pacchetto viene visualizzato sotto Pacchetti pubblicati nella pagina Gestisci pacchetti, selezionare l'icona a forma di matita accanto all'elenco dei pacchetti.

    Screenshot che mostra l'icona Modifica per un elenco di pacchetti in nuget.org.

  2. Nella pagina successiva selezionare Elenco, deselezionare la casella di controllo Elenco nei risultati della ricerca e quindi selezionare Salva.

    Screenshot che mostra la cancellazione della casella di controllo Elenco per un pacchetto in nuget.org.

Il pacchetto viene ora visualizzato in Pacchetti non elencati in Gestisci pacchetti e non viene più visualizzato nei risultati della ricerca.

Nota

Per evitare che il pacchetto di test sia attivo in nuget.org, è possibile eseguire il push nel sito di test nuget.org in https://int.nugettest.org. Si noti che i pacchetti caricati in int.nugettest.org potrebbero non essere mantenuti.

Aggiungere un file leggimi o un altro file

Per specificare direttamente i file da includere nel pacchetto, modificare il file di progetto e aggiungere la proprietà content:

<ItemGroup>
  <Content Include="readme.txt">
    <Pack>true</Pack>
    <PackagePath>\</PackagePath>
  </Content>
</ItemGroup>

In questo esempio, la proprietà specifica un file denominato readme.txt nella radice del progetto. Visual Studio visualizza il contenuto del file come testo normale immediatamente dopo l'installazione del pacchetto. I file leggimi non vengono visualizzati per i pacchetti installati come dipendenze. Ad esempio, ecco il file README per il pacchetto HtmlAgilityPack.

1 ----------------------------------------------------
2 ---------- Html Agility Pack Nuget Readme ----------
3 ----------------------------------------------------
4
5 ----Silverlight 4 and Windows Phone 7.1+ projects-----
6 To use XPATH features: System.Xml.Xpath.dll from the 3 Silverlight 4 SDK must be referenced.
7 This is normally found at
8 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client
9 or
10 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v4.0\Libraries\Client
11
12 ----Silverlight 5 projects-----
13 To use XPATH features: System.Xml.Xpath.dll from the Silverlight 5 SDK must be referenced.
14 This is normally found at
15 %ProgramFiles(x86)%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client
16 or
17 %ProgramFiles%\Microsoft SDKs\Microsoft SDKs\Silverlight\v5.0\Libraries\Client

Nota

Se aggiungi solo readme.txt alla radice del progetto senza includerlo nella proprietà content del file di progetto, non verrà incluso nel pacchetto.

Trova video NuGet su Channel 9 e YouTube.

Congratulazioni per la creazione di un pacchetto NuGet usando una libreria di classi .NET di Visual Studio. Passare all'articolo successivo per informazioni su come creare un pacchetto NuGet con Visual Studio .NET Framework.

Creare un pacchetto usando l'interfaccia della riga di comando di NuGet

Per altre informazioni sull'offerta di NuGet, vedere gli articoli seguenti: