Creare e pubblicare un pacchetto NuGet per .NET Standard

di Moreno Gentili, in ASP.NET Core,

Da qualche anno, ormai, siamo abituati ad usare pacchetti NuGet per ottenere componenti di terze parti ed integrarli nelle nostre applicazioni.
Chiunque può creare un pacchetto NuGet: è facile ed è un ottimo modo per incapsulare funzionalità che possiamo poi riutilizzare in vari nostri progetti, evitando fastidiosi copia-incolla. Come vedremo prossimamente, non siamo obbligati a rendere pubblici i nostri pacchetti NuGet ma li possiamo inviare ad un feed privato, affinché siano disponibili solo a noi e ai nostri collaboratori in azienda. Possiamo essere contemporaneamente autori ed utilizzatori dei nostri pacchetti.

In questo script vedremo come creare un pacchetto NuGet per .NET Standard 2.0. Nel caso non l'avessimo già fatto, installiamo il .NET Core 2.0 SDK dal seguente indirizzo.
https://www.microsoft.com/net/download/core

Creare il progetto

Da riga di comando, posizioniamoci in una cartella vuota e lanciamo il seguente comando per creare un nuovo progetto Class Library:

dotnet new classlib

Se stiamo usando Visual Studio 2017, possiamo ovviamente creare il progetto Class Library nella maniera tradizionale, ovvero selezionando l'apposito template tra quelli disponibili. Entrambi gli approcci produrranno lo stesso identico risultato.


Ora è il momento di far crescere il progetto implementando delle funzionalità. Quando siamo giunti ad un buon punto dello sviluppo della nostra libreria, passiamo alla fase di creazione e distribuzione del pacchetto NuGet.

Definire i metadati e le piattaforme supportate dal pacchetto NuGet

Prima di distribuire il pacchetto, è importante prestare attenzione alla versione di .NET Standard che stiamo usando. Essa determinerà le piattaforme (desktop, mobile e IoT) sulle quali la nostra libreria potrà funzionare. A tal proposito, facciamo riferimento alla tabella che illustra il supporto da parte delle varie piattaforme. (https://docs.microsoft.com/en-us/dotnet/standard/net-standard#net-implementation-support).

La versione è indicata all'interno del file di progetto .csproj. In questo esempio, la nostra libreria potrà essere usata su tutte le piattaforme che supportano .NET Standard 2.0.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>
</Project>

Inoltre, il file .csproj può essere integrato con una serie di metadati che forniranno informazioni sul pacchetto. Vediamo ad esempio quali metadati sono stati forniti a corredo del pacchetto NuGet Newtonsoft.Json (https://www.nuget.org/packages/Newtonsoft.Json/).


I metadati aiutano gli sviluppatori a trovare il pacchetto e capirne lo scopo generale, in modo che possano valutarne l'idoneità nel proprio scenario.
Integriamo quindi il nostro file .csproj nel seguente modo, indicando l'id del pacchetto (che non deve essere già in uso), la versione, una descrizione, il nome dell'autore, un link ad una pagina informativa, l'url dell'icona e una serie di tag di classificazione.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp2.0</TargetFramework>
  <PackageId>NomeMioPacchetto</PackageId>
  <Version>1.0.0</Version>
  <Description>Il mio primo pacchetto NuGet</Description>
    <Authors>Moreno Gentili</Authors>
    <PackageProjectUrl>http://www.example.ext/progetto/wiki</PackageProjectUrl>
    <PackageIconUrl>http://www.example.ext/progetto/icona.png</PackageIconUrl>
    <PackageTags>converter currency helper</PackageTags>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
  </PropertyGroup>
</Project>

Questi sono soltanto alcuni dei metadati che possiamo indicare. L'elenco completo è disponibile in questa pagina della documentazione (https://docs.microsoft.com/en-us/dotnet/core/tools/csproj#nuget-metadata-properties).

Ognuno dei metadati del pacchetto è impostabile anche da Visual Studio, da un'apposita sezione nelle proprietà del progetto.

Creare il pacchetto

Finalmente è tutto in ordine e possiamo generare il pacchetto. La generazione avviene subito dopo la compilazione se, nel nostro file .csproj, il nodo GeneratePackageOnBuild è stato impostato a true, come illustrato in un esempio precedente.

<GeneratePackageOnBuild>true</GeneratePackageOnBuild>

Il pacchetto consiste di un file .nupkg che troveremo all'interno della cartella /bin/Debug o /bin/Release, a seconda della configurazione usata all'atto della compilazione.

In alternativa, possiamo rigenerare il pacchetto in qualsiasi momento lanciando il comando dotnet pack dalla directory del progetto.

dotnet pack -c Release

Imparare ad usare la riga di comando è importante perché, creando degli script, riusciamo ad automatizzare dei compiti manuali e proni ad errori.

Pubblicare il pacchetto NuGet

Ora non resta che pubblicare il pacchetto affinché sia reso disponibile all'intera community di sviluppatori. Visitiamo l'url https://www.nuget.org e registriamo un account, oppure accediamo con il nostro account Microsoft esistente. Avremo a disposizione un'area riservata da cui potremo fare l'upload del file .nupkg.


In alternativa, l'upload può essere eseguito da linea di comando ma per far questo dobbiamo prima procurarci una API Key da https://www.nuget.org.


Al termine, potremo copiare la chiave che è stata appena generata.


Ora possiamo lanciare il comando di upload del pacchetto, ovviamente sostiuendo i valori NOMEPACCHETTO, VERSIONE e APIKEY in maniera appropriata.

dotnet nuget push bin\Release\NOMEPACCHETTO.VERSIONE.nupkg -k APIKEY

Quando desideriamo pubblicare un aggiornamento al pacchetto, ricordiamoci di incrementare la sua versione in accordo con le regole del semantic versioning (https://docs.microsoft.com/en-us/dotnet/core/versions/#semantic-versioning):

  • Incrementiamo la versione Major quando la nostra libreria ha subìto modifiche sostanziali, eventualmente introducendo delle breaking change che la rendono incompatibile con le precedenti versioni;
  • Incrementiamo la versione Minor se abbiamo aggiunto funzionalità senza alterare quelle implementate precedentemente;
  • Incrementiamo la versione Patch se abbiamo apportato dei bugfix che non alterano la API pubblica esposta dalla libreria.

Per consuetudine, la versione dell'assembly viene impostata per coincidere con quella dell'assembly, sebbene questo non sia un obbligo.

Commenti

Visualizza/aggiungi commenti

| Condividi su: Twitter, Facebook, LinkedIn

Per inserire un commento, devi avere un account.

Fai il login e torna a questa pagina, oppure registrati alla nostra community.

Approfondimenti

I più letti di oggi