PackageReference nei file di progetto

I riferimenti ai pacchetti, usando <PackageReference> gli elementi MSBuild, specificano le dipendenze del pacchetto NuGet direttamente all'interno dei file di progetto, anziché avere un file separato packages.config . L'uso di PackageReference non influisce su altri aspetti di NuGet; Ad esempio, le impostazioni nei NuGet.Config file (incluse le origini del pacchetto) vengono ancora applicate come illustrato in Configurazioni NuGet comuni.

Con PackageReference è anche possibile usare le condizioni di MSBuild per scegliere i riferimenti ai pacchetti per ogni framework di destinazione o altri raggruppamenti. Consente anche un controllo più capillare delle dipendenze e del flusso del contenuto. (Per altri dettagli, vedere Pack e restore di NuGet come destinazioni MSBuild .)

Supporto dei tipi di progetto

Per impostazione predefinita, PackageReference viene usato per i progetti .NET Core, i progetti .NET Standard e i progetti UWP destinati a Windows 10 Build 15063 (Creators Update) e versioni successive, con l'eccezione dei progetti UWP C++. I progetti .NET Framework supportano PackageReference, ma usano attualmente packages.config per impostazione predefinita. Per usare PackageReference, eseguire la migrazione delle dipendenze da packages.config nel file di progetto e quindi rimuovere packages.config.

Le app ASP.NET destinate a .NET Framework includono solo un supporto limitato per PackageReference. I tipi di progetto C++ e JavaScript non sono supportati.

Aggiunta di PackageReference

Aggiungere una dipendenza nel file di progetto usando la sintassi seguente:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Controllo della versione della dipendenza

La convenzione per specificare la versione di un pacchetto è uguale quando si usa packages.config:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

Nell'esempio precedente, 3.6.0 indica qualsiasi versione >=3.6.0 con preferenza per la versione più bassa, come descritto in Controllo delle versioni dei pacchetti.

Uso di PackageReference per un progetto senza dipendenze del pacchetto

Avanzato: se non si hanno pacchetti installati in un progetto (nessun PackageReference nel file di progetto e nessun file packages.config), ma si vuole ripristinare il progetto con stile PackageReference, è possibile impostare una proprietà del progetto RestoreProjectStyle su PackageReference nel file di progetto.

<PropertyGroup>
    <!--- ... -->
    <RestoreProjectStyle>PackageReference</RestoreProjectStyle>
    <!--- ... -->
</PropertyGroup>    

Questa opzione può essere utile se si fa riferimento a progetti con stile PackageReference (progetti con stile SDK o csproj esistenti). In questo modo, sarà possibile fare riferimento "in modo transitivo" dal progetto ai pacchetti a cui fanno riferimento tali progetti.

PackageReference e origini

Nei progetti PackageReference le versioni delle dipendenze transitive vengono risolte in fase di ripristino. Di conseguenza, nei progetti PackageReference tutte le origini devono essere disponibili per tutti i ripristini.

Versioni mobili

Le versioni mobili sono supportate con PackageReference:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.*" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0-beta.*" />
    <!-- ... -->
</ItemGroup>

Controllo degli asset delle dipendenze

È possibile che si usi una dipendenza esclusivamente come strumento di sviluppo e che non si voglia esporla nei progetti che utilizzano il pacchetto. In questo scenario, è possibile usare i metadati PrivateAssets per controllare questo comportamento.

<ItemGroup>
    <!-- ... -->

    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <PrivateAssets>all</PrivateAssets>
    </PackageReference>

    <!-- ... -->
</ItemGroup>

I tag di metadati seguenti controllano gli asset delle dipendenze:

I valori consentiti per questi tag sono i seguenti, con più valori separati da un punto e virgola, ad eccezione di all e none che devono essere usati da soli:

<ItemGroup>
    <!-- ... -->
    <!-- Everything except the content files will be consumed by the project -->
    <!-- Everything except content files and analyzers will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <IncludeAssets>all</IncludeAssets> <!-- Default is `all`, can be omitted-->
        <ExcludeAssets>contentFiles</ExcludeAssets>
        <PrivateAssets>contentFiles;analyzers</PrivateAssets>
    </PackageReference>
    <!-- ... -->
    <!-- Everything except the compile will be consumed by the project -->
    <!-- Everything except contentFiles will flow to the parent project-->
    <PackageReference Include="Contoso.Utility.SomeOtherUsefulStuff" Version="3.6.0">
        <ExcludeAssets>compile</ExcludeAssets>
        <PrivateAssets>contentFiles</PrivateAssets>
    </PackageReference>
    <!-- ... -->
</ItemGroup>

Si noti che dato che build non è incluso in PrivateAssets, le destinazioni e le proprietà verranno trasferite al progetto padre. Si consideri, ad esempio, che il riferimento precedente viene usato in un progetto che compila un pacchetto NuGet chiamato AppLogger. AppLogger può utilizzare le destinazioni e le proprietà da Contoso.Utility.UsefulStuff, analogamente ai progetti che utilizzano AppLogger.

Aggiunta di una condizione PackageReference

È possibile usare una condizione per controllare se un pacchetto è incluso e le condizioni possono usare qualsiasi variabile di MSBuild o una variabile definita nel file delle destinazioni o delle proprietà. Tuttavia, attualmente è supportata solo la variabile TargetFramework.

Ad esempio, si supponga di usare netstandard1.4 e net452 come destinazione, ma di avere una dipendenza applicabile solo per net452. In questo caso non si vuole che un progetto netstandard1.4 che utilizza il pacchetto aggiunta tale dipendenza non necessaria. Per evitarlo, è possibile specificare una condizione in PackageReference come segue:

<ItemGroup>
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" Condition="'$(TargetFramework)' == 'net452'" />
    <!-- ... -->
</ItemGroup>

Un pacchetto compilato con questo progetto indica che Newtonsoft.Json è incluso come dipendenza solo per una destinazione net452:

Le condizioni possono essere applicate anche al livello ItemGroup e verranno applicate a tutti gli elementi PackageReference figlio:

<ItemGroup Condition = "'$(TargetFramework)' == 'net452'">
    <!-- ... -->
    <PackageReference Include="Newtonsoft.Json" Version="9.0.1" />
    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0" />
    <!-- ... -->
</ItemGroup>

GeneratePathProperty

Questa funzionalità è disponibile con NuGet 5.0 o versione successiva e con Visual Studio 2019 16.0 o versione successiva.

A volte è consigliabile fare riferimento ai file in un pacchetto da una destinazione MSBuild. Nei packages.config progetti basati, i pacchetti vengono installati in una cartella relativa al file di progetto. Tuttavia, in PackageReference, i pacchetti vengono utilizzati dalla cartella global-packages , che può variare da computer a computer.

Per colmare tale gap, NuGet ha introdotto una proprietà che punta alla posizione da cui verrà utilizzato il pacchetto.

Esempio:

  <ItemGroup>
      <PackageReference Include="Some.Package" Version="1.0.0" GeneratePathProperty="true" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgSome_Package)\something.exe" />
  </Target>

NuGet genererà inoltre automaticamente le proprietà per i pacchetti contenenti una cartella degli strumenti.

  <ItemGroup>
      <PackageReference Include="Package.With.Tools" Version="1.0.0" />
  </ItemGroup>

  <Target Name="TakeAction" AfterTargets="Build">
    <Exec Command="$(PkgPackage_With_Tools)\tools\tool.exe" />
  </Target>

Le proprietà di MSBuild e le identità dei pacchetti non hanno le stesse restrizioni, pertanto l'identità del pacchetto deve essere modificata in un nome descrittivo di MSBuild, preceduto dalla parola Pkg. Per verificare il nome esatto della proprietà generata, esaminare il file nuget.g.props generato.

Alias PackageReference

In alcune rare istanze pacchetti diversi conterranno classi nello stesso spazio dei nomi. A partire da NuGet 5.7 & Visual Studio 2019 Update 7, equivalente a ProjectReference, PackageReference supporta Aliases. Per impostazione predefinita, non vengono forniti alias. Quando si specifica un alias, è necessario fare riferimento a tutti gli assembly provenienti dal pacchetto con annotazioni con un alias.

È possibile esaminare l'utilizzo di esempio in NuGet\Samples

Nel file di progetto specificare gli alias come segue:

  <ItemGroup>
    <PackageReference Include="NuGet.Versioning" Version="5.8.0" Aliases="ExampleAlias" />
  </ItemGroup>

e nel codice usarlo come segue:

extern alias ExampleAlias;

namespace PackageReferenceAliasesExample
{
...
        {
            var version = ExampleAlias.NuGet.Versioning.NuGetVersion.Parse("5.0.0");
            Console.WriteLine($"Version : {version}");
        }
...
}

Avvisi ed errori nuGet

Questa funzionalità è disponibile con NuGet 4.3 o versione successiva e con Visual Studio 2017 15.3 o versione successiva.

Per molti scenari di pacchetto e ripristino, tutti gli avvisi e gli errori NuGet vengono codificati e iniziano con NU****. Tutti gli avvisi e gli errori nuGet sono elencati nella documentazione di riferimento .

NuGet osserva le proprietà di avviso seguenti:

• TreatWarningsAsErrors, considera tutti gli avvisi come errori
• WarningsAsErrors, trattare avvisi specifici come errori
• NoWarn, nascondere avvisi specifici, a livello di progetto o a livello di pacchetto.

Esempi:

<PropertyGroup>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <WarningsAsErrors>$(WarningsAsErrors);NU1603;NU1605</WarningsAsErrors>
</PropertyGroup>
...
<PropertyGroup>
    <NoWarn>$(NoWarn);NU5124</NoWarn>
</PropertyGroup>
...
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0" NoWarn="NU1605" />
</ItemGroup>

Eliminazione degli avvisi nuGet

Sebbene sia consigliabile risolvere tutti gli avvisi NuGet durante le operazioni di pack e ripristino, in determinate situazioni è necessario eliminarli. Per eliminare un progetto di avviso a livello di avviso, è consigliabile eseguire le operazioni seguenti:

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
    <NoWarn>$(NoWarn);NU5104</NoWarn>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1"/>
</ItemGroup>

A volte gli avvisi si applicano solo a un determinato pacchetto nel grafico. È possibile scegliere di eliminare l'avviso in modo più selettivo aggiungendo un oggetto NoWarn nell'elemento PackageReference.

<PropertyGroup>
    <PackageVersion>5.0.0</PackageVersion>
</PropertyGroup>
<ItemGroup>
    <PackageReference Include="Contoso.Package" Version="1.0.0-beta.1" NoWarn="NU1603" />
</ItemGroup>

Eliminazione degli avvisi del pacchetto NuGet in Visual Studio

Quando si usa Visual Studio, è anche possibile eliminare gli avvisi tramite l'IDE.

Blocco delle dipendenze

Questa funzionalità è disponibile con NuGet 4.9 o versione successiva e con Visual Studio 2017 15.9 o versione successiva.

L'input per il ripristino NuGet è un set di elementi del file di PackageReference progetto (dipendenze dirette o di primo livello) e l'output è una chiusura completa di tutte le dipendenze del pacchetto, incluse le dipendenze transitive. NuGet prova a produrre sempre la stessa chiusura completa di dipendenze del pacchetto se l'elenco PackageReference di input non è stato modificato. Esistono tuttavia alcuni scenari in cui non è possibile farlo. Ad esempio:

• Quando si usano versioni mobili, ad esempio <PackageReference Include="My.Sample.Lib" Version="4.*"/>. Anche se in questo caso la finalità è il passaggio alla versione più recente a ogni ripristino dei pacchetti, esistono scenari in cui gli utenti richiedono che il grafo venga bloccato su una determinata versione più recente e passi a una versione successiva, se disponibile, in caso di movimento esplicito.

• Viene pubblicata una versione più recente del pacchetto che risponde ai requisiti di versione di PackageReference. ad esempio

  • Giorno 1: si è specificato <PackageReference Include="My.Sample.Lib" Version="4.0.0"/>, ma le versioni disponibili nei repository NuGet erano 4.1.0, 4.2.0 e 4.3.0. In questo caso, NuGet restituirebbe 4.1.0 (la versione minima più vicina)

  • Giorno 2: viene pubblicata la versione 4.0.0. NuGet troverà ora la corrispondenza esatta e inizierà a restituire 4.0.0

• Una versione del pacchetto specifica viene rimossa dal repository. Anche se nuget.org non consente eliminazioni di pacchetti, non tutti i repository di pacchetti hanno questo vincolo. NuGet trova di conseguenza la corrispondenza migliore quando non può restituire la versione eliminata.

Abilitazione del file di blocco

Per rendere persistente la chiusura completa delle dipendenze del pacchetto, è possibile acconsentire esplicitamente alla funzionalità di file di blocco impostando la proprietà MSBuild RestorePackagesWithLockFile per il progetto:

<PropertyGroup>
    <!--- ... -->
    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
    <!--- ... -->
</PropertyGroup>    

Se questa proprietà viene impostata, il ripristino NuGet genererà un file di blocco, il file packages.lock.json, nella directory radice del progetto, che elenca tutte le dipendenze del pacchetto.

Comportamento di restore con il file di blocco

Se un file di blocco è presente per il progetto, NuGet lo usa per eseguire restore. NuGet esegue un rapido controllo per verificare se sono state apportate modifiche alle dipendenze del pacchetto indicate nel file di progetto (o nei file dei progetti dipendenti) e, se non sono presenti modifiche, si limita a ripristinare i pacchetti indicati nel file di blocco. Non viene eseguita alcuna rivalutazione delle dipendenze del pacchetto.

Se NuGet rileva una modifica nelle dipendenze definite indicate nei file di progetto, rivaluta il grafo del pacchetto e aggiorna il file di blocco in modo da riflettere la nuova chiusura del pacchetto per il progetto.

Per CI/CD e altri scenari in cui non si vogliono modificare le dipendenze del pacchetto immediatamente, è possibile farlo impostando lockedmode su true:

Per dotnet.exe, eseguire:

> dotnet.exe restore --locked-mode

Per msbuild.exe, eseguire:

> msbuild.exe -t:restore -p:RestoreLockedMode=true

È anche possibile impostare questa proprietà MSBuild condizionale nel file di progetto:

<PropertyGroup>
    <!--- ... -->
    <RestoreLockedMode>true</RestoreLockedMode>
    <!--- ... -->
</PropertyGroup> 

Se la modalità di blocco è true, verranno ripristinati i pacchetti esatti elencati nel file di blocco. Il ripristino avrà invece esito negativo se le dipendenze del pacchetto definite per il progetto sono state aggiornate dopo la creazione del file di blocco.

Rendere il file di blocco parte del repository di origine

Se si compila un'applicazione, un file eseguibile e il progetto in questione sono alla inizio della catena di dipendenze, quindi archiviare il file di blocco nel repository di codice sorgente in modo che NuGet possa usarlo durante il ripristino.

Se tuttavia il progetto è un progetto libreria che non viene distribuito o un progetto di codice comune da cui dipendono altri progetti, non è consigliabile archiviare il file di blocco come parte del codice sorgente. È possibile mantenere il file di blocco, ma le dipendenze del pacchetto bloccato per il progetto di codice comune, elencate nel file di blocco, non possono essere usate durante il ripristino o la compilazione di un progetto che dipende da questo progetto di codice comune.

Ad esempio:

ProjectA
  |------> PackageX 2.0.0
  |------> ProjectB
             |------>PackageX 1.0.0

Se ProjectA ha una dipendenza da PackageX versione 2.0.0 e fa anche riferimento a ProjectB che dipende da PackageX versione 1.0.0, il file di blocco per ProjectB elencherà una dipendenza da PackageX versione 1.0.0. Tuttavia, quando ProjectA viene compilato, il relativo file di blocco conterrà una dipendenza dalla PackageX versione 2.0.0 e non 1.0.0 come elencato nel file di blocco per ProjectB. Di conseguenza, il file di blocco di un progetto di codice comune ha poca influenza sui pacchetti risolti per i progetti che dipendono da esso.

Estendibilità di file di blocco

È possibile controllare diversi comportamenti di ripristino con file di blocco, come descritto di seguito:

Sistema di risoluzione delle dipendenze NuGet

Il sistema di risoluzione delle dipendenze NuGet segue le 4 regole descritte nel documento sulla risoluzione delle dipendenze.

Per migliorare le prestazioni e la scalabilità dell'operazione di ripristino, l'algoritmo di ripristino è stato riscritto nella versione 6.12. A partire dalla versione 6.12, il nuovo algoritmo di ripristino è abilitato per impostazione predefinita per tutti i progetti PackageReference. Anche se il nuovo algoritmo di ripristino è funzionalmente equivalente a quello precedente, come per qualsiasi software, sono possibili bug. Per ripristinare l'implementazione precedente, impostare la proprietà RestoreUseLegacyDependencyResolver MSBuild su true.

Se si verificano errori di ripristino nella versione 6.12, .NET 9 o 17.12, che non sono stati riprodotti nelle versioni precedenti, segnalare un problema in GitHub. Eventuali differenze tra gli algoritmi precedenti e quelli nuovi possono avere effetti diversi, ad esempio durante la compilazione o in fase di esecuzione. È anche possibile che le modifiche non comportino errori, ma versioni del pacchetto diverse ripristinate. Se si ritiene di essere interessati da eventuali modifiche, ecco i passaggi che è possibile eseguire per verificare se le modifiche nell'algoritmo di ripristino NuGet sono la causa radice.

Il ripristino scrive i risultati nella MSBuildProjectExtensionsPath directory, che possono essere confrontati con gli algoritmi nuovi e precedenti per individuare le differenze. In genere si tratta della obj cartella della compilazione. È possibile usare msbuild.exe o dotnet.exe per i passaggi successivi.

1. Rimuovere la obj cartella per il progetto.
2. Eseguire msbuild -t:restore
3. Salvare il contenuto di in obj una posizione che indica che si tratta del new comportamento.
4. Eseguire msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true"
5. Salvare il contenuto di in obj una posizione che indica che si tratta del legacy comportamento.
6. Confrontare i file nelle due directory, in particolare project.assets.json. Gli strumenti che possono evidenziare le differenze sono particolarmente utili per questo (ad esempio, Visual Studio Code, aprire entrambi i file e usare il pulsante destro del mouse su "seleziona per confrontare" e "confrontare con selezionato")

Se si segue il metodo precedente, dovrebbe esserci esattamente 1 differenza tra i project.assets.json file:

      "projectStyle": "PackageReference",
+     "restoreUseLegacyDependencyResolver": true,
      "fallbackFolders": [

Se sono presenti altre differenze, segnalare un problema in GitHub con tutti i dettagli.

AssetTargetFallback

La AssetTargetFallback proprietà consente di specificare versioni aggiuntive del framework compatibili per i progetti a cui fa riferimento il progetto e i pacchetti NuGet utilizzati dal progetto.

Se si specifica una dipendenza del pacchetto usando PackageReference ma tale pacchetto non contiene asset compatibili con il framework di destinazione dei progetti, la AssetTargetFallback proprietà entra in gioco. La compatibilità del pacchetto a cui si fa riferimento viene ricontrollata usando ogni framework di destinazione specificato in AssetTargetFallback. Quando viene fatto riferimento a o project package tramite AssetTargetFallback, verrà generato l'avviso NU1701 .

Per esempi di AssetTargetFallback impatto sulla compatibilità, vedere la tabella seguente.

È possibile specificare più framework usando ; come delimitatore. Per aggiungere un framework di fallback, è possibile eseguire le operazioni seguenti:

<AssetTargetFallback Condition=" '$(TargetFramework)'=='netcoreapp3.1' ">
    $(AssetTargetFallback);net472;net471
</AssetTargetFallback>

Se si desidera sovrascrivere, è possibile evitare $(AssetTargetFallback) di aggiungere ai valori esistenti AssetTargetFallback .