Pacchetti di distribuzione di .NET

  • Articolo

Man mano che .NET 5 (e .NET Core) e le versioni successive diventano disponibili in più piattaforme, è utile imparare a creare pacchetti, assegnare nomi e versioni alle app e alle librerie che lo usano. In questo modo, coloro che si occupano della manutenzione dei pacchetti possono garantire un'esperienza coerente indipendentemente dalla piattaforma scelta dagli utenti per l'esecuzione di .NET. Questo articolo è utile per gli utenti che:

  • Tentativo di compilazione .NET dal codice sorgente.
  • Richiesta di modifiche all'interfaccia della riga di comando di .NET che possono avere effetti sul layout risultante o sui pacchetti prodotti.

Layout dei dischi

Quando viene installato, .NET è costituito da diversi componenti che vengono disposti nel file system come segue:

{dotnet_root}                    (0)              (*)
├── dotnet                       (1)
├── LICENSE.txt                  (8)
├── ThirdPartyNotices.txt        (8)
├── host                                          (*)
│   └── fxr                                       (*)
│       └── <fxr version>        (2)
├── sdk                                           (*)
│   └── <sdk version>            (3)
├── sdk-manifests                (4)              (*)
│   └── <sdk feature band version>
├── library-packs                (4)              (*)
├── metadata                     (4)              (*)
│   └── workloads
│       └── <sdk feature band version>
├── template-packs               (4)              (*)
├── packs                                         (*)
│   ├── Microsoft.AspNetCore.App.Ref              (*)
│   │   └── <aspnetcore ref version>     (11)
│   ├── Microsoft.NETCore.App.Ref                 (*)
│   │   └── <netcore ref version>        (12)
│   ├── Microsoft.NETCore.App.Host.<rid>          (*)
│   │   └── <apphost version>            (13)
│   ├── Microsoft.WindowsDesktop.App.Ref          (*)
│   │   └── <desktop ref version>        (14)
│   ├── NETStandard.Library.Ref                   (*)
│   │   └── <netstandard version>        (15)
│   ├── Microsoft.NETCore.App.Runtime.<rid>       (*)
│   │   └── <runtime version>            (18)
│   └── Microsoft.AspNetCore.App.Runtime.<rid>    (*)
│       └── <aspnetcore version>         (18)
├── shared                                        (*)
│   ├── Microsoft.NETCore.App                     (*)
│   │   └── <runtime version>     (5)
│   ├── Microsoft.AspNetCore.App                  (*)
│   │   └── <aspnetcore version>  (6)
│   ├── Microsoft.AspNetCore.All                  (*)
│   │   └── <aspnetcore version>  (6)
│   └── Microsoft.WindowsDesktop.App              (*)
│       └── <desktop app version> (7)
└── templates                                     (*)
│   └── <templates version>      (17)
/
├── etc/dotnet
│       └── install_location     (16)
├── usr/share/man/man1
│       └── dotnet.1.gz          (9)
└── usr/bin
        └── dotnet               (10)

  • (0) {dotnet_root} è una radice condivisa per tutte le versioni principali e secondarie di .NET. Se sono installati più runtime, condividono la cartella {dotnet_root}, ad esempio {dotnet_root}/shared/Microsoft.NETCore.App/6.0.11 e {dotnet_root}/shared/Microsoft.NETCore.App/7.0.0. Il nome della cartella {dotnet_root} deve essere indipendente dalla versione, ovvero semplicemente dotnet.

  • (1) dotnet L'host, noto anche come "muxer", ha due ruoli distinti: attivare un runtime per avviare un'applicazione e attivare un SDK per inviare comandi all'applicazione. L'host è un file eseguibile nativo (dotnet.exe).

Benché sia presente un singolo host, la maggior parte degli altri componenti si trova in directory con versioni (2,3,5,6). Questo significa che nel sistema possono essere presenti più versioni installate side-by-side.

  • (2) host/fxr/<versione fxr> contiene la logica di risoluzione del framework usata dall'host. L'host usa la versione di hostfxr più recente installata. Hostfxr è responsabile della selezione del runtime appropriato durante l'esecuzione di un'applicazione .NET. Ad esempio, un'applicazione compilata per .NET 7.0.0 usa il runtime 7.0.5 quando è disponibile. Analogamente, hostfxr seleziona l'SDK appropriato durante lo sviluppo.

  • (3) sdk/<versione sdk> L'SDK, noto anche come "strumenti", è un set di strumenti gestiti che vengono usati per scrivere e compilare applicazioni e librerie .NET. L'SDK include l'interfaccia della riga di comando di .NET, i compilatori di linguaggi gestiti, MSBuild, le attività di compilazione e le destinazioni associate, NuGet, nuovi modelli di progetto e così via.

  • (4) sdk-manifests/<sdk feature band version> I nomi e le versioni degli asset richiesti da un'installazione facoltativa del carico di lavoro vengono mantenuti nei manifesti del carico di lavoro archiviati in questa cartella. Il nome della cartella è la versione della banda di funzionalità dell'SDK. Per una versione dell'SDK come 7.0.102, questa cartella sarà ancora denominata 7.0.100. Quando viene installato un carico di lavoro, le cartelle seguenti vengono create in base alle esigenze degli asset del carico di lavoro: pacchetto-libreria, metadati e pacchetto-modello. Una distribuzione può creare un file /metadata/workloads/<sdkfeatureband>/userlocal vuoto se i carichi di lavoro devono essere installati in un percorso utente anziché nella cartella dotnet. Per altre informazioni, vedere il problema di GitHub dotnet/installer#12104.

La cartella shared contiene i framework. Un framework condiviso offre un set di librerie in una posizione centrale per consentirne l'uso da parte di applicazioni diverse.

  • (5) shared/Microsoft.NETCore.App/<versione runtime> Questo framework contiene il runtime di .NET e il supporto delle librerie gestite.

  • (6) shared/Microsoft.AspNetCore.{App,All}/<versione aspnetcore> contiene le librerie ASP.NET Core. Le librerie in Microsoft.AspNetCore.App vengono sviluppate e supportate come parte del progetto .NET. Le librerie in Microsoft.AspNetCore.All sono un superset che contiene anche le librerie di terze parti.

  • (7) shared/Microsoft.Desktop.App/<versione app desktop> contiene le librerie desktop di Windows. Non è inclusa nelle piattaforme non Windows.

  • (8) LICENSE.txt,ThirdPartyNotices.txt sono rispettivamente le licenze di .NET e le licenze delle librerie di terze parti usate in .NET.

  • (9,10) dotnet.1.gz, dotnet dotnet.1.gz è la pagina di manuale dotnet. dotnet è un collegamento simbolico all'host dotnet (1). Questi file vengono installati in percorsi ben noti per l'integrazione del sistema.

  • (11.12) Microsoft.NETCore.App.Ref,Microsoft.AspNetCore.App.Ref descrivono rispettivamente l'API di una versione x.y di .NET e di ASP.NET Core. Questi pacchetti vengono usati durante la compilazione per tali versioni di destinazione.

  • (13) Microsoft.NETCore.App.Host.<rid> contiene un file binario nativo per la piattaforma rid. Questo file binario è un modello per la compilazione di un'applicazione .NET in un file binario nativo per tale piattaforma.

  • (14) Microsoft.WindowsDesktop.App.Ref descrive l'API della versione x.y delle applicazioni desktop di Windows. Questi file vengono usati durante la compilazione per tale destinazione. Questo non viene fornito nelle piattaforme non Windows.

  • (15) NETStandard.Library.Ref descrive l'API netstandard x.y. Questi file vengono usati durante la compilazione per tale destinazione.

  • (16) /etc/dotnet/install_location è un file che contiene il percorso completo di {dotnet_root}. Il percorso può terminare con una nuova riga. Non è necessario aggiungere questo file quando la radice è /usr/share/dotnet.

  • (17) i modelli contengono i modelli usati dall'SDK. Ad esempio, dotnet new trova qui i modelli di progetto.

  • (18) Microsoft.NETCore.App.Runtime.<rid>/<versione runtime>,Microsoft.AspNetCore.App.Runtime.<rid>/<versione aspnetcore> Questi file consentono la creazione di applicazioni autonome. Queste directory contengono collegamenti simbolici ai file in (2), (5) e (6).

Le cartelle contrassegnate con (*) vengono utilizzate da più pacchetti. Alcuni formati di pacchetto, ad esempio rpm, richiedono una gestione speciale di tali cartelle. Il manutentore del pacchetto deve occuparsi di questo.

Il controllo delle versioni di .NET è basato sui numeri di versione [major].[minor] del componente di runtime. La versione dell'SDK usa gli stessi elementi [major].[minor] e ha un elemento [patch] indipendente che combina la semantica della versione definitiva e della versione patch per l'SDK. Ad esempio: la versione 7.0.302 dell'SDK è la seconda versione patch della terza versione definitiva dell'SDK che supporta il runtime 7.0. Per altre informazioni sul controllo delle versioni, vedere Panoramica di come viene specificata la versione di .NET.

Alcuni pacchetti includono parte del numero di versione nel nome. Questo consente di installare una versione specifica. La parte rimanente della versione non è inclusa nel nome della versione. Ciò consente alla gestione pacchetti del sistema operativo di aggiornare i pacchetti, ad esempio installando automaticamente le correzioni per la sicurezza. La gestione pacchetti supportata è specifica per Linux.

Di seguito sono elencati i pacchetti consigliati:

  • dotnet-sdk-[major].[minor] - Installa l'SDK più recente per un runtime specifico

    • Versione:<sdk>
    • Esempio: dotnet-sdk-7.0
    • Contiene: (3),(4),(18)
    • Dipendenze: dotnet-runtime-[major].[minor], aspnetcore-runtime-[major].[minor], dotnet-targeting-pack-[major].[minor], aspnetcore-targeting-pack-[major].[minor], netstandard-targeting-pack-[netstandard_major].[netstandard_minor], dotnet-apphost-pack-[major].[minor], dotnet-templates-[major].[minor]

  • aspnetcore-runtime-[major].[minor] - Installa un runtime ASP.NET Core specifico

    • Versione:<versione del runtime aspnetcore>
    • Esempio: aspnetcore-runtime-7.0
    • Contiene: (6)
    • Dipendenze:dotnet-runtime-[major].[minor]

  • dotnet-runtime-deps-[major].[minor](Facoltativo): installa le dipendenze per l'esecuzione di applicazioni autonome

    • Versione:<versione di runtime>
    • Esempio: dotnet-runtime-deps-7.0
    • Dipendenze: dipendenze specifiche della distribuzione

  • dotnet-runtime-[major].[minor] - Installa un runtime specifico

    • Versione:<versione di runtime>
    • Esempio: dotnet-runtime-7.0
    • Contiene: (5)
    • Dipendenze: dotnet-hostfxr-[major].[minor], dotnet-runtime-deps-[major].[minor]

  • dotnet-hostfxr-[major].[minor]- dipendenza

    • Versione:<versione di runtime>
    • Esempio: dotnet-hostfxr-7.0
    • Contiene: (2)
    • Dipendenze:dotnet-host

  • dotnet-host- dipendenza

    • Versione:<versione di runtime>
    • Esempio: dotnet-host
    • Contiene: (1),(8),(9),(10),(16)

  • dotnet-apphost-pack-[major].[minor]- dipendenza

    • Versione:<versione di runtime>
    • Contiene: (13)

  • dotnet-targeting-pack-[major].[minor] - Consente di indirizzarsi a un runtime non recentissimo

    • Versione:<versione di runtime>
    • Contiene: (12)

  • aspnetcore-targeting-pack-[major].[minor] - Consente di indirizzarsi a un runtime non recentissimo

    • Versione:<versione del runtime aspnetcore>
    • Contiene: (11)

  • netstandard-targeting-pack-[netstandard_major].[netstandard_minor] - Consente di indirizzarsi a una versione netstandard

    • Versione:<sdk>
    • Contiene: (15)

  • dotnet-templates-[major].[minor]

    • Versione:<sdk>
    • Contiene: (17)

I due pacchetti meta seguenti sono facoltativi. Apportano valore agli utenti finali in quanto astraggono il pacchetto di primo livello (dotnet-sdk), che semplifica l'installazione del set completo di pacchetti .NET. Questi meta pacchetti fanno riferimento a una versione specifica dell’SDK .NET.

  • dotnet[major] - Installa la versione dell'SDK specificata

    • Versione:<sdk>
    • Esempio: dotnet7
    • Dipendenze:dotnet-sdk-[major].[minor]

  • dotnet - Installa una versione specifica dell'SDK, determinata dalle distribuzioni come versione primaria, in genere la versione più recente disponibile

    • Versione:<sdk>
    • Esempio: dotnet
    • Dipendenze:dotnet-sdk-[major].[minor]

dotnet-runtime-deps-[major].[minor] richiede la comprensione delle dipendenze specifiche della distribuzione. Poiché il sistema di compilazione della distribuzione può derivare automaticamente, il pacchetto è facoltativo, nel qual caso queste dipendenze vengono aggiunte direttamente al pacchetto dotnet-runtime-[major].[minor].

Quando il contenuto del pacchetto si trova in una cartella con versione, il nome [major].[minor] del pacchetto corrisponde al nome della cartella con versione. Per tutti i pacchetti, ad eccezione di netstandard-targeting-pack-[netstandard_major].[netstandard_minor], questo corrisponde anche alla versione di .NET.

Le dipendenze tra i pacchetti devono usare un requisito di versione uguale o maggiore di. Ad esempio, dotnet-sdk-7.0:7.0.401 richiede aspnetcore-runtime-7.0 >= 7.0.6. Ciò consente all'utente di aggiornare l'installazione tramite un pacchetto radice (ad esempio, dnf update dotnet-sdk-7.0).

Per la maggior parte delle distribuzioni è necessario che tutti gli elementi vengano compilati dall'origine. Questo ha un certo impatto sui pacchetti:

  • Le librerie di terze parti in shared/Microsoft.AspNetCore.All non possono essere compilate facilmente dal codice sorgente. Quindi la cartella viene omessa dal pacchetto aspnetcore-runtime.

  • NuGetFallbackFolder viene popolato usando elementi binari da nuget.org. Deve rimanere vuoto.

Più pacchetti dotnet-sdk possono contenere gli stessi file per NuGetFallbackFolder. Per evitare problemi con la gestione pacchetti, questi file devono essere identici (checksum, data di modifica e così via).

Eseguire il debug dei pacchetti

Il contenuto di debug deve essere incluso in pacchetti denominati di debug che seguono la divisione del pacchetto .NET descritta in precedenza in questo articolo. Ad esempio, il contenuto di debug del pacchetto dotnet-sdk-[major].[minor] deve essere incluso in un pacchetto denominato dotnet-sdk-dbg-[major].[minor]. È necessario installare il contenuto di debug nella stessa posizione dei file binari.

Ecco alcuni esempi binari:

Nella directory {dotnet_root}/sdk/<sdk version> sono previsti i due file seguenti:

  • dotnet.dll - installato con il pacchetto dotnet-sdk-[major].[minor]
  • dotnet.pdb - installato con il pacchetto dotnet-sdk-dbg-[major].[minor]

Nella directory {dotnet_root}/shared/Microsoft.NETCore.App/<runtime version> sono previsti i due file seguenti:

  • System.Text.Json.dll - installato con il pacchetto dotnet-runtime-[major].[minor]
  • System.Text.Json.pdb - installato con il pacchetto dotnet-runtime-dbg-[major].[minor]

Nella directory {dotnet_root/shared/Microsoft.AspNetCore.App/<aspnetcore version> sono previsti i due file seguenti:

  • Microsoft.AspNetCore.Routing.dll - installato con i pacchetti aspnetcore-runtime-[major].[minor]
  • Microsoft.AspNetCore.Routing.pdb - installato con i pacchetti aspnetcore-runtime-dbg-[major].[minor]

A partire da .NET 8.0, tutti i contenuti di debug .NET (file PDB), prodotti dalla compilazione di origine, sono disponibili in un file tarball denominato dotnet-symbols-sdk-<version>-<rid>.tar.gz. Questo archivio contiene PDB nelle sottodirectory, che corrispondono alla struttura di directory del tarball SDK .NET - dotnet-sdk-<version>-<rid>.tar.gz.

Anche se tutto il contenuto di debug è disponibile nel file tarball di debug, non tutto il contenuto di debug è altrettanto importante. Gli utenti finali sono principalmente interessati al contenuto delle directory shared/Microsoft.AspNetCore.App/<aspnetcore version> e shared/Microsoft.NETCore.App/<runtime version>.

Il contenuto dell'SDK in sdk/<sdk version> è utile per il debug dei set di strumenti dell’SDK .NET.

I pacchetti seguenti sono i pacchetti di debug consigliati:

  • aspnetcore-runtime-dbg-[major].[minor] - Installa il contenuto di debug per un runtime specifico di ASP.NET Core

    • Versione:<versione del runtime aspnetcore>
    • Esempio: aspnetcore-runtime-dbg-8.0
    • Contiene: contenuto di debug per (6)
    • Dipendenze:aspnetcore-runtime-[major].[minor]

  • dotnet-runtime-dbg-[major].[minor] - Installa il contenuto di debug per un runtime specifico

    • Versione:<versione di runtime>
    • Esempio: dotnet-runtime-dbg-8.0
    • Contiene: contenuto di debug per (5)
    • Dipendenze:dotnet-runtime-[major].[minor]

Il pacchetto di debug seguente è facoltativo:

  • dotnet-sdk-dbg-[major].[minor] - Installa il contenuto di debug per una versione specifica dell'SDK
    • Versione:<sdk>
    • Esempio: dotnet-sdk-dbg-8.0
    • Contiene: contenuto di debug per (3),(4),(18)
    • Dipendenze:dotnet-sdk-[major].[minor]

Il file tarball di debug contiene anche contenuto di debug in packs, che rappresenta le copie del contenuto in shared. Nel layout .NET la directory packs viene usata per la compilazione di applicazioni .NET. Non esistono scenari di debug, pertanto non è consigliabile creare un pacchetto del contenuto di debug in packs, nel file tarball di debug.

Compilazione dei pacchetti

Il repository dotnet/source-build contiene istruzioni su come compilare un file tarball di origine di .NET SDK e tutti i relativi componenti. L'output del repository di compilazione dell'origine corrisponde al layout descritto nella prima sezione di questo articolo.