Condividi tramite

Guida introduttiva: Creare e pubblicare un pacchetto con l'interfaccia della riga di comando dotnet

  • Articolo

Questa guida introduttiva illustra come creare rapidamente un pacchetto NuGet da una libreria di classi .NET e pubblicarlo in nuget.org usando l'interfaccia della riga di comando .NET o l'interfaccia della riga di comando dotnet.

Prerequisiti

  • .NET SDK, che fornisce lo strumento da riga di comando dotnet. A partire da Visual Studio 2017, l'interfaccia della riga di comando dotnet viene installata automaticamente con qualsiasi carico di lavoro correlato a .NET o .NET Core.

  • Un account gratuito su nuget.org. Seguire le istruzioni in Aggiungere un nuovo account singolo.

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 o creare un progetto semplice come indicato di seguito:

  1. Creare una cartella denominata AppLogger.
  2. Aprire un prompt dei comandi e passare alla cartella AppLogger . Per impostazione predefinita, tutti i comandi dell'interfaccia della riga di comando dotnet in questa guida introduttiva vengono eseguiti nella cartella corrente.
  3. Immettere dotnet new classlib, che crea un progetto con il nome della cartella corrente.

Per altre informazioni, vedere dotnet new.

Aggiungere i metadati del pacchetto al file di progetto

Ogni pacchetto NuGet ha un manifesto che descrive il contenuto e le dipendenze del pacchetto. Nel pacchetto finale il manifesto è un file con estensione nuspec , che usa le proprietà dei metadati NuGet incluse nel file di progetto.

Aprire il file di progetto con estensione csproj, fsproj o vbproj e aggiungere le proprietà seguenti all'interno del tag esistente<PropertyGroup>. Usare i valori personalizzati per nome e società e sostituire l'identificatore del pacchetto con un valore univoco.

<PackageId>Contoso.08.28.22.001.Test</PackageId>
<Version>1.0.0</Version>
<Authors>your_name</Authors>
<Company>your_company</Company>

Importante

L'identificatore del pacchetto deve essere univoco tra nuget.org e altre origini del pacchetto. La pubblicazione rende il pacchetto visibile pubblicamente, quindi se si usa la libreria AppLogger di esempio o un'altra libreria di test, usare un nome univoco che include Sample o Test.

È possibile aggiungere eventuali proprietà facoltative descritte in Proprietà dei metadati NuGet.

Nota

Per i pacchetti compilati per l'utilizzo pubblico, prestare particolare attenzione alla PackageTags proprietà . I tag aiutano gli altri a trovare il pacchetto e a capire cosa fa.

Eseguire il comando pack

Per compilare un pacchetto NuGet o un file con estensione nupkg dal progetto, eseguire il comando dotnet pack , che compila automaticamente anche il progetto.

dotnet pack

L'output mostra il percorso del file con estensione nupkg :

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Restored C:\Users\myname\source\repos\AppLogger\AppLogger.csproj (in 64 ms).
  AppLogger -> C:\Users\myname\source\repos\AppLogger\bin\Debug\net6.0\AppLogger.dll
  Successfully created package 'C:\Users\myname\source\repos\AppLogger\bin\Debug\Contoso.08.28.22.001.Test.1.0.0.nupkg'.

Generare automaticamente il pacchetto in fase di compilazione

Per eseguire dotnet pack automaticamente ogni volta che si esegue dotnet build, aggiungere la riga seguente al file di progetto all'interno di <PropertyGroup>:

    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Pubblicare il pacchetto

Pubblicare il file con estensione nupkg in nuget.org usando il comando push nuget dotnet con una chiave API ottenuta 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 i propri feed NuGet.

Ottenere la chiave dell'API

  1. Accedi al tuo account nuget.org o crea un account se non ne hai già uno.

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

  3. Selezionare Crea e specificare un nome per la chiave.

  4. In Seleziona ambiti selezionare Push.

  5. In Seleziona modello Glob pacchetti>immettere *.

  6. Seleziona Crea.

  7. Selezionare Copia per copiare la nuova chiave.

    Screenshot che mostra la nuova chiave API con il collegamento Copia.

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 rigenerarla per copiarla. È anche possibile rimuovere la chiave API se non si vuole più eseguire il push dei pacchetti.

L'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 dotnet nuget push

Dalla cartella che contiene il file con estensione nupkg eseguire il comando seguente. Specificare il nome file con estensione nupkg e sostituire il valore della chiave con la chiave 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 all'indirizzo https://int.nugettest.org. Si noti che i pacchetti caricati in int.nugettest.org potrebbero non essere mantenuti.

Errori di pubblicazione

Gli errori dal 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 push comando 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 con estensione nupkg e ripetere il push comando.

Gestire il pacchetto pubblicato

Quando il pacchetto viene pubblicato correttamente, si riceve un messaggio di posta elettronica di conferma. Per visualizzare il pacchetto appena pubblicato, in nuget.org selezionare il nome utente in alto a destra e quindi 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 elencati e 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 del pacchetto per nasconderlo dai risultati della ricerca:

  1. Dopo che il pacchetto viene visualizzato in Pacchetti pubblicati nella pagina Gestisci pacchetti, selezionare l'icona a forma di matita accanto all'elenco di 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 all'indirizzo https://int.nugettest.org. Si noti che i pacchetti caricati in int.nugettest.org potrebbero non essere mantenuti.

Congratulazioni per la creazione e la pubblicazione del primo pacchetto NuGet.

Trova altri video NuGet su Channel 9 e YouTube.

Passaggi successivi

Vedere altri dettagli su come creare pacchetti con l'interfaccia della riga di comando dotnet:

Creare un pacchetto NuGet con l'interfaccia della riga di comando dotnet

Altre informazioni sulla creazione e la pubblicazione di pacchetti NuGet: