Guida introduttiva: Creare e pubblicare un pacchetto usando Visual Studio (.NET Framework, Windows)

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

La guida introduttiva è destinata solo agli utenti di Windows. Se si usa Visual Studio per Mac, vedere invece dotnet CLI tools.

Prerequisiti

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

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

    Visual Studio 2017 e versioni successive include automaticamente funzionalità NuGet quando viene installato un carico di lavoro .NET.

  • 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

Per creare un progetto di libreria di classi, seguire questa procedura:

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

  2. Nella finestra Creare un nuovo progetto selezionare C#, Windows e Library negli elenchi a discesa.

  3. Nell'elenco risultante dei modelli di progetto selezionare Class Library (.NET Framework) e quindi selezionare Next.

  4. Nella finestra Configurare la nuova finestra project immettere AppLogger per il nome Project e quindi selezionare Crea.

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

  6. (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 questo pacchetto di esempio, includere il codice seguente:

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

    All'interno di un pacchetto NuGet reale, è probabile che si implementino molte funzionalità utili con cui altri utenti possono compilare applicazioni. È anche possibile impostare i framework di destinazione. Per un esempio, vedi UWP.

Configurare le proprietà del progetto per il pacchetto

Un pacchetto NuGet include un manifesto (un .nuspec file), che contiene metadati pertinenti, ad esempio l'identificatore del pacchetto, il numero di versione, la descrizione e altro ancora. Alcuni di questi metadati possono essere estratti direttamente dalle proprietà del progetto, evitando di doverli aggiornare separatamente sia nel progetto che nel manifeste. I passaggi seguenti descrivono come impostare le proprietà applicabili:

  1. Selezionare Project > Proprietà e quindi selezionare la scheda Application.

  2. Per Nome assembly assegnare al pacchetto un identificatore univoco. Se si tenta di pubblicare un pacchetto con un nome già esistente, viene visualizzato un errore.

    Importante

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

  3. Selezionare Informazioni assembly, che visualizza una finestra di dialogo in cui è possibile immettere altre proprietà che vengono incluse nel manifesto (vedere Token di sostituzione). I campi usati più comunemente sono Titolo, Descrizione, Società, Copyright e Versione assembly. Poiché queste proprietà vengono visualizzate con il pacchetto in un host come nuget.org dopo la pubblicazione, assicurarsi che siano completamente descrittive.

    Screenshot che mostra la pagina delle Informazioni sull'assembly in un progetto .NET Framework in Visual Studio.

  4. (Facoltativo) Per visualizzare e modificare direttamente le proprietà, aprire il file Properties/AssemblyInfo.cs nel project selezionando Project>Edit Project File.

  5. Dopo aver impostato queste proprietà, impostare la configurazione della soluzione Active in Build>Configuration Manager su Release e ricompilare il progetto per generare la DLL aggiornata.

Generare il manifesto iniziale

Dopo aver impostato le proprietà del progetto e aver creato la DLL, è ora possibile generare un file con estensione nuspec iniziale dal progetto. Questo passaggio include i token di sostituzione pertinenti per estrarre informazioni dal file del progetto.

Eseguire nuget spec una sola volta per generare il manifesto iniziale. Se aggiorni il pacchetto, modifica i valori nel tuo progetto, oppure modifica direttamente il manifesto:

  1. Con il progetto aperto in Solution Explorer, aprire un prompt dei comandi selezionando Strumenti>Riga di comando>Developer Command Prompt.

    Il prompt dei comandi viene aperto nella directory del progetto in cui si trova il AppLogger.csproj file.

  2. Eseguire il comando seguente: nuget spec AppLogger.csproj.

    NuGet crea un manifesto che corrisponde al nome del progetto, in questo caso AppLogger.nuspec. Include anche i token di sostituzione nel manifest.

  3. Aprire AppLogger.nuspec in un editor di testo per esaminarne il contenuto, che sarà simile al codice seguente:

    <?xml version="1.0"?>
<package >
  <metadata>
    <id>Package</id>
    <version>1.0.0</version>
    <authors>Your username</authors>
    <owners>Your username</owners>
    <license type="expression">MIT</license>
    <!-- <icon>icon.png</icon> -->
    <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>Package description</description>
    <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
    <copyright>Copyright 2022</copyright>
    <tags>Tag1 Tag2</tags>
  </metadata>
</package>

Modificare il manifesto

  1. Modificare le proprietà seguenti prima di procedere. In caso contrario, se si tenta di creare un pacchetto NuGet con i valori predefiniti nel .nuspec file, si verifica un errore. Per informazioni su queste proprietà, vedere Elementi di metadati facoltativi:

    • licenseUrl
    • projectUrl
    • note di rilascio
    • tags

  2. Per i pacchetti creati per l'utilizzo pubblico, prestare particolare attenzione alla proprietà Tags , in quanto i tag aiutano altri a trovare il pacchetto e a capire cosa fa.

  3. È anche possibile aggiungere altri elementi al manifesto in questo momento - come descritto nel file nuspec.

  4. Salvare il file prima di procedere.

Eseguire il comando pack

  1. Con il progetto aperto in Solution Explorer, aprire un prompt dei comandi selezionando Strumenti>Riga di comando>Developer Command Prompt.

    Il prompt dei comandi si apre nella directory del progetto.

  2. Eseguire il comando seguente: nuget pack.

    NuGet genera un file con estensione nupkg sotto forma di identifier.version.nupkg nella cartella corrente.

Pubblicare il pacchetto

Dopo aver creato un file con estensione nupkg , pubblicarlo in nuget.org usando l'interfaccia della riga di comando di NuGet con una chiave API acquisita da nuget.org. Per nuget.org, è necessario usare nuget.exe la versione 4.1.0 o successiva.

Se si vuole testare e convalidare il pacchetto prima di pubblicarlo una raccolta pubblica, è possibile caricarlo in un ambiente di test come int.nugettest.org anziché nuget.org. Si noti che i pacchetti caricati in int.nugettest.org potrebbero non essere mantenuti.

Note

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

  • I pacchetti che pubblichi su nuget.org sono visibili pubblicamente ad altri sviluppatori, a meno che non vengano rimossi dall'elenco. Per ospitare i pacchetti in modo privato, vedere Ospitare i propri feed NuGet.

Acquisire la chiave API

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

  2. Nell'angolo in alto a destra selezionare il nome utente e quindi chiavi API.

  3. Selezionare Crea e quindi immettere un nome per la chiave.

  4. In Seleziona ambiti selezionare Push.

  5. Sotto Select Packages, per Glob Pattern, immettere un asterisco (*).

  6. Fare clic su Crea.

  7. Selezionare Copia per copiare la nuova chiave.

    Screenshot di una pagina nuget.org che mostra la nuova chiave API, un messaggio sulla copia della chiave ora e il pulsante Copia evidenziato.

Importante

  • Mantenere sempre la chiave API un segreto. La chiave API è simile a una password che chiunque può usare per gestire i pacchetti per conto dell'utente. Eliminare o rigenerare la chiave API se viene accidentalmente rivelata.
  • 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.

La 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 la CLI di NuGet

L'uso dell'interfaccia della riga di comando di NuGet (nuget.exe) è un'alternativa all'uso dell'interfaccia della riga di comando di .NET:

  1. Aprire un prompt dei comandi e passare alla cartella contenente il file con estensione nupkg .

  2. Esegui il comando seguente: Sostituire <il nome file> del pacchetto con il nome file del pacchetto e sostituire <il valore> della chiave API con la chiave API. Il nome file del pacchetto è una concatenazione dell'ID pacchetto e del numero di versione con estensione .nupkg . Ad esempio, AppLogger.1.0.0.nupkg:

    nuget push <package filename> <api key value> -Source https://api.nuget.org/v3/index.json

    Il risultato del processo di pubblicazione viene visualizzato come segue:

    Pushing <package filename> to 'https://www.nuget.org/api/v2/package'...
    PUT https://www.nuget.org/api/v2/package/
    Created https://www.nuget.org/api/v2/package/ 6829ms
Your package was pushed.

Per altre informazioni, vedere nuget push.

Errori di pubblicazione

Quando si esegue il push comando, a volte si verifica un errore. Ad esempio, è possibile che venga visualizzato un errore nelle situazioni seguenti:

  • La chiave API non è valida o è scaduta.
  • Si tenta di pubblicare un pacchetto con un identificatore già esistente nell'host.
  • Si apportano modifiche a un pacchetto pubblicato, ma si dimentica di aggiornare il numero di versione prima di riprovare a pubblicarlo.

Il messaggio di errore indica in genere l'origine del problema.

Si supponga, ad esempio, che l'identificatore Contoso.App.Logger.Test esista in nuget.org. Se si tenta di pubblicare un pacchetto con tale identificatore, viene visualizzato 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.).

Per risolvere questa situazione, controllare l'ambito, la data di scadenza e il valore della chiave API. Se la chiave è valida, l'errore indica che l'identificatore del pacchetto esiste già nell'host. Per risolvere il problema, 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 pubblicato, passare a nuget.org, selezionare il nome utente nell'angolo in alto a destra e quindi selezionare Gestisci pacchetti.

Note

L'indicizzazione e la visualizzazione del pacchetto nei risultati della ricerca potrebbero richiedere alcuni minuti. Durante tale periodo, il pacchetto viene visualizzato in Pacchetti non elencati e la pagina del pacchetto mostra il messaggio seguente:

Screenshot di un messaggio di avviso nuget.org relativo al pacchetto non ancora pubblicato. Il testo indica che la convalida e l'indicizzazione possono richiedere un'ora.

Ora che il pacchetto NuGet viene pubblicato in nuget.org, altri sviluppatori possono usarlo nei progetti.

Se si crea un pacchetto che non è utile (ad esempio questo pacchetto di esempio da una libreria di classi vuota) o se non si vuole che il pacchetto sia visibile, è possibile rimuovere 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 della pagina pacchetti nuget.org. La sezione Pacchetti pubblicati elenca un pacchetto. L'icona di modifica è evidenziata.

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

    Screenshot di una pagina nuget.org. Nella sezione Elenco è evidenziata l'opzione per elencare il pacchetto nei risultati della ricerca.

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

Note

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.

Passaggi successivi

Congratulazioni per la creazione di un pacchetto NuGet usando il framework di Visual Studio .NET. Passare all'articolo successivo per informazioni su come creare un pacchetto NuGet con l'interfaccia della riga di comando di NuGet.

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

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

  • Last updated on