project.json e UWP

Importante

Questo contenuto è deprecato. I progetti devono usare i formati PackageReference. Scopri come migrare il tuo progetto project.json a PackageReference. Visual Studio 2026 esegue automaticamente la migrazione di project.json in fase di caricamento della soluzione. .NET 10 SDK & NuGet.exe 7.0 non supportano i progetti project.json.

Questo documento descrive la struttura del pacchetto che usa funzionalità in NuGet 3+ (Visual Studio 2015 e versioni successive). La proprietà minClientVersion del .nuspec può essere usata per dichiarare che sono necessarie le funzionalità descritte qui impostandola su 3.1.

Aggiunta del supporto UWP a un pacchetto esistente

Se hai un pacchetto esistente e vuoi aggiungere il supporto per le applicazioni UWP, non devi adottare il formato di creazione pacchetti descritto qui. È necessario adottare questo formato solo se sono necessarie le funzionalità descritte e sono disposte a lavorare solo con i client che hanno eseguito l'aggiornamento alla versione 3+ del client NuGet.

Ho già come destinazione netcore45

Se hai già come destinazione netcore45 e non è necessario sfruttare le funzionalità qui, non è necessaria alcuna azione. I pacchetti netcore45 possono essere utilizzati dalle applicazioni UWP.

Voglio sfruttare le API specifiche di Windows 10

In questo caso è necessario aggiungere l'identificatore del framework di destinazione uap10.0 (TFM o TxM) al pacchetto. Creare una nuova cartella nel pacchetto e aggiungere l'assembly compilato per funzionare con Windows 10 a tale cartella.

Non ho bisogno di API specifiche per Windows 10, ma voglio nuove funzionalità .NET o non ho già netcore45.

In questo caso, aggiungi il TxM dotnet al pacchetto. A differenza di altri TxMs, dotnet non implica una superficie o una piattaforma. Indica che il pacchetto funziona su qualsiasi piattaforma su cui funzionano le dipendenze. Quando si compila un pacchetto con il dotnet TxM, è probabile che si abbiano molte altre dipendenze specifiche di TxM nel .nuspec, perché è necessario definire i pacchetti BCL da cui dipende, ad esempio System.Text, System.Xmle così via. Le posizioni su cui funzionano tali dipendenze definiscono dove funziona il pacchetto.

Come è possibile individuare le dipendenze

Esistono due modi per individuare le dipendenze da elencare:

1. Usare il generatore di dipendenze NuSpec strumento di di terze parti. Lo strumento automatizza il processo e aggiorna il file .nuspec con i pacchetti dipendenti durante la fase di build. È disponibile tramite un pacchetto NuGet, NuSpec.ReferenceGenerator.

2. (La strada più difficile) Utilizzate ILDasm per esaminare il .dll per vedere quali assembly sono realmente necessarie durante l'esecuzione. Determinare quindi da quale pacchetto NuGet provengono.

Vedere l'argomento project.json per informazioni dettagliate sulle funzionalità utili per la creazione di un pacchetto che supporta il dotnet TxM.

Importante

Se il pacchetto è progettato per lavorare con progetti PCL, è consigliabile creare una cartella dotnet, per evitare avvisi e potenziali problemi di compatibilità.

Struttura della directory

I pacchetti NuGet che usano questo formato hanno le cartelle e i comportamenti noti seguenti:

Cartella	Comportamenti
Costruire	Contiene i target e i file props di MSBuild in questa cartella che sono integrati in modo diverso nel progetto; altrimenti, non ci sono modifiche.
Strumenti	install.ps1 e uninstall.ps1 non vengono eseguiti. init.ps1 funziona come sempre.
Contenuto	Il contenuto non viene copiato automaticamente nel progetto di un utente. Il supporto per l'inclusione di contenuto nel progetto è pianificato per una versione successiva.
Lib	Per molti pacchetti, il lib funziona allo stesso modo di NuGet 2.x, ma con opzioni ampliate per i nomi che possono essere utilizzati al suo interno e una logica migliorata per scegliere la sottocartella corretta durante l'utilizzo dei pacchetti. Tuttavia, se usato insieme a ref, la cartella lib contiene gli assembly che implementano la superficie definita dagli assembly nella cartella ref.
Ref	ref è una cartella facoltativa che contiene assembly .NET che definiscono la superficie pubblica (tipi e metodi pubblici) a cui un'applicazione deve adattarsi per la compilazione. Gli assembly in questa cartella potrebbero non avere implementazioni, ma vengono usati esclusivamente per definire la superficie di attacco per il compilatore. Se il pacchetto non ha una cartella ref, il lib è sia l'assembly di riferimento che l'assembly di implementazione.
Runtime	runtimes è una cartella facoltativa che contiene codice specifico del sistema operativo, ad esempio l'architettura della CPU e i file binari specifici del sistema operativo o altrimenti dipendenti dalla piattaforma.

Obiettivi e file props di MSBuild nei pacchetti

I pacchetti NuGet possono contenere .targets e .props file importati in qualsiasi progetto MSBuild in cui è installato il pacchetto. In NuGet 2.x questa operazione è stata eseguita inserendo istruzioni <Import> nel file .csproj, in NuGet 3.0 non è presente alcuna azione specifica di "installazione al progetto". Il processo di ripristino del pacchetto scrive invece due file [projectname].nuget.props e [projectname].NuGet.targets.

MSBuild è in grado di cercare questi due file e li importa automaticamente vicino all'inizio e alla fine del processo di compilazione del progetto. Ciò offre un comportamento molto simile a NuGet 2.x, ma con una differenza importante: non esiste un ordine garantito di file targets/props in questo caso. Tuttavia, MSBuild offre modi per ordinare le destinazioni tramite gli attributi BeforeTargets e AfterTargets della definizione di <Target> (vedere Elemento di destinazione (MSBuild).

Lib e Ref

Il comportamento della cartella lib non è cambiato in modo significativo in NuGet v3. Tuttavia, tutti gli assembly devono trovarsi all'interno di sottocartelle denominate dopo un TxM e non possono più essere posizionati direttamente nella cartella lib. Un TxM è il nome di una piattaforma per cui dovrebbe funzionare un determinato asset in un pacchetto. Logicamente si tratta di un'estensione dei Moniker del Framework di destinazione (TFM), ad esempio net45, net46, netcore50e dnxcore50 sono tutti esempi di TxMs (vedere i Framework di destinazione ). TxM può fare riferimento a un framework (TFM) e ad altre aree di superficie specifiche della piattaforma. Ad esempio, il TxM UWP (uap10.0) rappresenta la superficie di attacco .NET e l'area di attacco di Windows per le applicazioni UWP.

Struttura lib di esempio:

lib
├───net40
│       MyLibrary.dll
└───wp81
        MyLibrary.dll

La cartella lib contiene assembly usati in fase di esecuzione. Per la maggior parte dei pacchetti una cartella in lib per ogni txms di destinazione è tutto ciò che è necessario.

Ref

In alcuni casi è consigliabile usare un assembly diverso durante la compilazione (gli assembly di riferimento .NET eseguono questa operazione oggi). Per questi casi, usare una cartella di primo livello denominata ref (abbreviazione di "Assembly di riferimento").

La maggior parte degli autori di pacchetti non richiede la cartella ref. È utile per i pacchetti che devono fornire una superficie coerente per la compilazione e IntelliSense, ma hanno un'implementazione diversa per diversi TxMs. Il caso d'uso più importante di questo è costituito dai pacchetti System.* prodotti come parte della spedizione di .NET Core in NuGet. Questi pacchetti hanno diverse implementazioni che vengono unificate da un set coerente di assembly di riferimento.

Meccanicamente, gli assembly inclusi nella cartella ref sono gli assembly di riferimento passati al compilatore. Per coloro che hanno usato csc.exe, questi sono gli assembly che stiamo passando all'opzione di riferimento /reference nello switch C#.

La struttura della cartella ref è uguale a lib, ad esempio:

└───MyImageProcessingLib
        ├───lib
        │   ├───net40
        │   │       MyImageProcessingLibrary.dll
        │   │
        │   ├───net451
        │   │       MyImageProcessingLibrary.dll
        │   │
        │   └───win81
        │           MyImageProcessingLibrary.dll
        │
        └───ref
            ├───net40
            │       MyImageProcessingLibrary.dll
            │
            └───portable-net451-win81
                    MyImageProcessingLibrary.dll

In questo esempio gli assembly nelle directory ref sarebbero tutti identici.

Runtime

La cartella runtime contiene assembly e librerie native necessarie per l'esecuzione in "runtime" specifici, generalmente definiti dall'architettura del sistema operativo e della CPU. Questi runtime vengono identificati usando identificatori di runtime ( RID), ad esempio win, win-x86, win7-x86, win8-64e così via.

Helper nativi per l'uso di API specifiche della piattaforma

L'esempio seguente mostra un pacchetto con un'implementazione puramente gestita per diverse piattaforme, ma usa helper nativi in Windows 8 in cui può chiamare le API native specifiche di Windows 8.

└───MyLibrary
        ├───lib
        │   └───net40
        │           MyLibrary.dll
        │
        └───runtimes
            ├───win8-x64
            │   ├───lib
            │   │   └───net40
            │   │           MyLibrary.dll
            │   │
            │   └───native
            │           MyNativeLibrary.dll
            │
            └───win8-x86
                ├───lib
                │   └───net40
                │           MyLibrary.dll
                │
                └───native
                        MyNativeLibrary.dll

Dato il pacchetto precedente, vengono eseguite le operazioni seguenti:

• Quando non è in Windows 8 viene usato l'assembly lib/net40/MyLibrary.dll.

• Quando si utilizza Windows 8, il runtimes/win8-<architecture>/lib/MyLibrary.dll viene usato e il native/MyNativeHelper.dll viene copiato nell'output della tua compilazione.

Nell'esempio precedente, l'assembly lib/net40 è puramente gestito, mentre gli assembly nella cartella runtimes utilizzeranno P/Invoke nell'assembly helper nativo per invocare API specifiche di Windows 8.

Viene selezionata una sola cartella lib, quindi se esiste una cartella specifica del runtime, essa viene scelta al posto di una cartella libnon specifica del runtime. La cartella nativa è aggiuntiva, se esistente viene copiata nell'output della compilazione.

Wrapper gestito

Un altro modo per usare i runtime consiste nel distribuire un pacchetto che è puramente un wrapper gestito su un assembly nativo. In questo scenario si crea un pacchetto simile al seguente:

└───MyLibrary
        └───runtimes
            ├───win8-x64
            │   ├───lib
            │   │   └───net451
            │   │           MyLibrary.dll
            │   │
            │   └───native
            │           MyImplementation.dll
            │
            └───win8-x86
                ├───lib
                │   └───net451
                │           MyLibrary.dll
                │
                └───native
                        MyImplementation.dll

In questo caso non esiste alcuna cartella lib di primo livello perché non esiste alcuna implementazione di questo pacchetto che non si basa sull'assembly nativo corrispondente. Se l'assembly gestito, MyLibrary.dll, era esattamente lo stesso in entrambi questi casi, è possibile inserirlo in una cartella di livello superiore lib, ma poiché la mancanza di un assembly nativo non causa l'installazione del pacchetto se è stata installata in una piattaforma che non era win-x86 o win-x64, la libreria di livello superiore verrebbe usata ma non verrebbe copiato alcun assembly nativo.

Creazione di pacchetti per NuGet 2 e NuGet 3

Se si vuole creare un pacchetto che può essere utilizzato dai progetti usando packages.config e i pacchetti che usano project.json, si applica quanto segue:

• Ref e runtime funzionano solo in NuGet 3. Entrambi vengono ignorati da NuGet 2.

• Non è possibile fare affidamento su install.ps1 o uninstall.ps1 per funzionare. Questi file vengono eseguiti quando si usa packages.config, ma vengono ignorati con project.json. Quindi il pacchetto deve essere utilizzabile senza eseguirli. init.ps1 ancora in esecuzione su NuGet 3.

• L'installazione di destinazioni e oggetti di scena è diversa, quindi assicurati che il pacchetto funzioni come previsto su entrambi i clienti.

• Le sottodirectory di lib devono essere un TxM in NuGet 3. Non è possibile inserire librerie nella radice della cartella lib.

• Il contenuto non viene copiato automaticamente con NuGet 3. I consumatori del tuo pacchetto possono copiare i file da soli o usare uno strumento come un task runner per automatizzare la copia dei file.

• Le trasformazioni di file di origine e configurazione non vengono eseguite da NuGet 3.

Se si supporta NuGet 2 e 3, il minClientVersion deve essere la versione più bassa del client NuGet 2 su cui funziona il pacchetto. Nel caso di un pacchetto esistente, non dovrebbe essere necessario modificare.