NuGet pack e ripristino come MSBuild destinazioni

NuGet 4.0+

Con il formato PackageReference , NuGet 4.0+ può archiviare tutti i metadati del manifesto direttamente all'interno di un file di progetto anziché usare un file separato .nuspec .

Con MSBuild 15.1+, NuGet è anche un cittadino di prima classe MSBuild con gli pack obiettivi e restore come descritto di seguito. Queste destinazioni consentono di usare NuGet come si farebbe con qualsiasi altra MSBuild attività o destinazione. Per istruzioni sulla creazione di un pacchetto con MSBuild, vedere Creare un NuGet pacchetto con MSBuild.NuGet (Per NuGet 3.x e versioni precedenti, si usano invece i comandi pack e restore tramite l'interfaccia della NuGet riga di comando.

Ordine di compilazione delle destinazioni

Poiché pack e restore sono MSBuild destinazioni, è possibile accedervi per migliorare il flusso di lavoro. Si supponga, ad esempio, di voler copiare il pacchetto in una condivisione di rete dopo averlo creato. È possibile farlo aggiungendo quanto segue nel file di progetto:

<Target Name="CopyPackage" AfterTargets="Pack">
  <Copy
    SourceFiles="$(OutputPath)..\$(PackageId).$(PackageVersion).nupkg"
    DestinationFolder="\\myshare\packageshare\"
    />
</Target>

Analogamente, è possibile scrivere un'attività MSBuild , scrivere la propria destinazione e utilizzare NuGet le proprietà nell'attività MSBuild .

Destinazione pack

Per i progetti .NET che usano il PackageReference formato , utilizzando msbuild -t:pack disegna input dal file di progetto da usare per la creazione di un NuGet pacchetto.

Nella tabella seguente vengono descritte le MSBuild proprietà che è possibile aggiungere a un file di progetto all'interno del primo <PropertyGroup> nodo. È possibile apportare facilmente queste modifiche in Visual Studio 2017 e versioni successive facendo clic con il pulsante destro del mouse sul progetto e scegliendo Modifica {nome_progetto} dal menu di scelta rapida. Per praticità, la tabella è organizzata in base alla proprietà equivalente in un .nuspec file.

Input destinazione pack

Scenari pack

Eliminazione delle dipendenze

Per eliminare le dipendenze dei pacchetti dal pacchetto generato NuGet , impostare su SuppressDependenciesWhenPacking true che consentirà di ignorare tutte le dipendenze dal file nupkg generato.

PackageIconUrl

PackageIconUrl è deprecato a favore della PackageIcon proprietà . NuGet A partire dalla versione 5.3 e Visual Studio 2019 versione 16.3, pack genera l'avviso NU5048 se i metadati del pacchetto specificano PackageIconUrlsolo .

PackageIcon

Compressione di un file di immagine icona

Quando si crea il pacchetto di un file di immagine icona, usare PackageIcon la proprietà per specificare il percorso del file icona, relativo alla radice del pacchetto. Assicurarsi inoltre che il file sia incluso nel pacchetto. Le dimensioni del file di immagine sono limitate a 1 MB. I formati di file supportati includono JPEG e PNG. È consigliabile una risoluzione dell'immagine di 128x128.

Ad esempio:

<PropertyGroup>
    ...
    <PackageIcon>icon.png</PackageIcon>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="images\icon.png" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

Esempio di icona del pacchetto.

Per l'equivalente nuspec , vedere riferimento per nuspec l'icona.

PackageReadmeFile

Supportato con NuGet 5.10.0 preview 2.NET / SDK 5.0.300 e versioni successive

Quando si esegue la compressione di un file readme, è necessario usare la PackageReadmeFile proprietà per specificare il percorso del pacchetto, rispetto alla radice del pacchetto. Oltre a questo, è necessario assicurarsi che il file sia incluso nel pacchetto. I formati di file supportati includono solo Markdown (.md).

Ad esempio:

<PropertyGroup>
    ...
    <PackageReadmeFile>readme.md</PackageReadmeFile>
    ...
</PropertyGroup>

<ItemGroup>
    ...
    <None Include="docs\readme.md" Pack="true" PackagePath="\"/>
    ...
</ItemGroup>

Per l'equivalente nuspec , vedere il nuspec riferimento per readme.

Assembly di output

nuget pack copia i file di output con le estensioni .exe, .dll, .xml, .winmd, .json e .pri. I file di output copiati dipendono da ciò che MSBuild fornisce dalla BuiltOutputProjectGroup destinazione.

Esistono due MSBuild proprietà che è possibile usare nel file di progetto o nella riga di comando per controllare dove vanno gli assembly di output:

• IncludeBuildOutput: valore booleano che determina se gli assembly di output della compilazione devono essere inclusi nel pacchetto.
• BuildOutputTargetFolder: specifica la cartella in cui devono essere posizionati gli assembly di output. Gli assembly di output (e altri file di output) vengono copiati nelle rispettive cartelle per framework.

Riferimenti ai pacchetti

Vedere Riferimenti ai pacchetti nei file di progetto.

Riferimenti da progetto a progetto

I riferimenti da progetto a progetto vengono considerati per impostazione predefinita come NuGet riferimenti al pacchetto. Ad esempio:

<ProjectReference Include="..\UwpLibrary2\UwpLibrary2.csproj"/>

È anche possibile aggiungere i metadati seguenti ai riferimenti del progetto:

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Inclusione di contenuto in un pacchetto

Per includere il contenuto, aggiungere altri metadati all'elemento <Content> esistente. Per impostazione predefinita tutti gli elementi di tipo"Content" vengono inclusi nel pacchetto, a meno che non si esegua l'override con voci simili al codice seguente:

<Content Include="..\win7-x64\libuv.txt">
 <Pack>false</Pack>
</Content>

Per impostazione predefinita, tutti gli elementi vengono aggiunti alla radice di content e della cartella contentFiles\any\<target_framework> all'interno di un pacchetto e viene mantenuta la struttura di cartelle relative, a meno che non si specifichi un percorso di pacchetto:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles\</PackagePath>
</Content>

Se si desidera copiare tutto il contenuto in una o più cartelle radice specifiche (anziché content e contentFiles entrambe), è possibile usare la MSBuild proprietà ContentTargetFolders, che per impostazione predefinita è "content; contentFiles" ma può essere impostato su qualsiasi altro nome di cartella. Si noti che se si specifica solo "contentFiles" in ContentTargetFolders, i file vengono posizionati in contentFiles\any\<target_framework> o contentFiles\<language>\<target_framework> in base a buildAction.

PackagePath può essere un set di percorsi di destinazione delimitati da punto e virgola. Se si specifica un percorso di pacchetto vuoto, il file viene aggiunto alla radice del pacchetto. Ad esempio, il codice seguente aggiunge libuv.txt a content\myfiles, content\samples e nella radice del pacchetto:

<Content Include="..\win7-x64\libuv.txt">
  <Pack>true</Pack>
  <PackagePath>content\myfiles;content\sample;;</PackagePath>
</Content>

Esiste anche una MSBuild proprietà $(IncludeContentInPack), che per impostazione predefinita è true. Se questa proprietà è impostata su false in qualsiasi progetto, il contenuto di tale progetto non viene incluso nel nuget pacchetto.

Altri metadati specifici del pacchetto che è possibile impostare su uno degli elementi precedenti includono e quali impostano CopyToOutput e Flatten i valori nella contentFiles voce nell'output nuspec.<PackageFlatten> <PackageCopyToOutput>

IncludeSymbols

Quando si usa MSBuild -t:pack -p:IncludeSymbols=true, i file .pdb corrispondenti vengono copiati insieme agli altri file di output (.dll, .exe, .winmd, .xml, .json, .pri). Si noti che l'impostazione IncludeSymbols=true crea un pacchetto regolare e un pacchetto di simboli.

IncludeSource

Equivale a IncludeSymbols, ma insieme ai file .pdb vengono copiati anche i file di origine. Tutti i file di tipo Compile vengono copiati in src\<ProjectName>\ conservando la struttura di cartelle del percorso relativo nel pacchetto risultante. Lo stesso accade anche per i file di origine di qualsiasi ProjectReference con TreatAsPackageReference impostato su false.

Se un file di tipo Compile è all'esterno della cartella di progetto, viene semplicemente aggiunto a src\<ProjectName>\.

Compressione di un'espressione di licenza o di un file di licenza

Quando si usa un'espressione di licenza, usare la PackageLicenseExpression proprietà . Per un esempio, vedere Esempio di espressione di licenza.

<PropertyGroup>
    <PackageLicenseExpression>MIT</PackageLicenseExpression>
</PropertyGroup>

Per altre informazioni sulle espressioni di licenza e sulle licenze accettate da NuGet.org, vedere metadati delle licenze.

Quando si crea il pacchetto di un file di licenza, usare PackageLicenseFile la proprietà per specificare il percorso del pacchetto, relativo alla radice del pacchetto. Assicurarsi inoltre che il file sia incluso nel pacchetto. Ad esempio:

<PropertyGroup>
    <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
</PropertyGroup>

<ItemGroup>
    <None Include="licenses\LICENSE.txt" Pack="true" PackagePath=""/>
</ItemGroup>

Per un esempio, vedere Esempio di file di licenza.

Compressione di un file senza estensione

In alcuni scenari, ad esempio durante la compressione di un file di licenza, potrebbe essere necessario includere un file senza estensione. Per motivi cronologici, NuGet e MSBuild trattare i percorsi senza estensione come directory.

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0</TargetFrameworks>
    <PackageLicenseFile>LICENSE</PackageLicenseFile>
  </PropertyGroup>

  <ItemGroup>
    <None Include="LICENSE" Pack="true" PackagePath=""/>
  </ItemGroup>  

File senza un esempio di estensione.

IsTool

Quando si usa MSBuild -t:pack -p:IsTool=true, tutti i file, come specificato nello scenario Assembly di output, vengono copiati nella cartella tools invece che nella cartella lib. Si noti che questo comportamento è diverso da DotNetCliTool, che viene specificato impostando PackageType nel file .csproj.

Compressione con un .nuspec file

Sebbene sia consigliabile includere tutte le proprietà in genere presenti nel .nuspec file di progetto, è possibile scegliere di usare un .nuspec file per comprimere il progetto. Per un progetto non in stile SDK che usa PackageReference, è necessario importare NuGet.Build.Tasks.Pack.targets in modo che l'attività pack possa essere eseguita. È comunque necessario ripristinare il progetto prima di poter comprimere un nuspec file. Per impostazione predefinita, un progetto in stile SDK include le destinazioni pack.

Il framework di destinazione del file di progetto è irrilevante e non viene usato per la compressione di un oggetto nuspec. Le tre MSBuild proprietà seguenti sono rilevanti per la compressione tramite un oggetto .nuspec:

1. NuspecFile: percorso relativo o assoluto per il file .nuspec usato per la creazione del pacchetto.
2. NuspecProperties: elenco con valori delimitati da punto e virgola di coppie chiave=valore. A causa del funzionamento MSBuild dell'analisi della riga di comando, è necessario specificare più proprietà nel modo seguente: -p:NuspecProperties="key1=value1;key2=value2".
3. NuspecBasePath: percorso di base per il file .nuspec.

Se si usa dotnet.exe per creare il pacchetto del progetto, usare un comando simile al seguente:

dotnet pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path> 

Se si usa MSBuild per creare il pacchetto del progetto, usare un comando simile al seguente:

msbuild -t:pack <path to .csproj file> -p:NuspecFile=<path to nuspec file> -p:NuspecProperties=<> -p:NuspecBasePath=<Base path> 

Si noti che la compressione di un nuspec oggetto utilizzando dotnet.exe o msbuild anche la compilazione del progetto per impostazione predefinita. Ciò può essere evitato passando la --no-build proprietà a dotnet.exe, che è l'equivalente dell'impostazione <NoBuild>true</NoBuild> nel file di progetto, insieme all'impostazione <IncludeBuildOutput>false</IncludeBuildOutput> nel file di progetto.

Un esempio di file con estensione csproj per comprimere un nuspec file è:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <NoBuild>true</NoBuild>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <NuspecFile>PATH_TO_NUSPEC_FILE</NuspecFile>
    <NuspecProperties>add nuspec properties here</NuspecProperties>
    <NuspecBasePath>optional to provide</NuspecBasePath>
  </PropertyGroup>
</Project>

Punti di estensione avanzati per creare un pacchetto personalizzato

La pack destinazione fornisce due punti di estensione eseguiti nella build specifica del framework di destinazione interno. I punti di estensione supportano l'inclusione di contenuto e assembly specifici del framework di destinazione in un pacchetto:

• TargetsForTfmSpecificBuildOutput target: usare per i file all'interno della lib cartella o di una cartella specificata tramite BuildOutputTargetFolder.
• TargetsForTfmSpecificContentInPackage target: usare per i file all'esterno di BuildOutputTargetFolder.

TargetsForTfmSpecificBuildOutput

Scrivere una destinazione personalizzata e specificarla come valore della $(TargetsForTfmSpecificBuildOutput) proprietà . Per tutti i file che devono essere inseriti in BuildOutputTargetFolder (lib per impostazione predefinita), la destinazione deve scrivere tali file in ItemGroup BuildOutputInPackage e impostare i due valori di metadati seguenti:

• FinalOutputPath: percorso assoluto del file; se non specificato, l'identità viene usata per valutare il percorso di origine.
• TargetPath: (Facoltativo) Impostare quando il file deve entrare in una sottocartella all'interno lib\<TargetFramework> di , ad esempio gli assembly satellite che si trovano nelle rispettive cartelle delle impostazioni cultura. Il valore predefinito è il nome del file.

Esempio:

<PropertyGroup>
  <TargetsForTfmSpecificBuildOutput>$(TargetsForTfmSpecificBuildOutput);GetMyPackageFiles</TargetsForTfmSpecificBuildOutput>
</PropertyGroup>

<Target Name="GetMyPackageFiles">
  <ItemGroup>
    <BuildOutputInPackage Include="$(OutputPath)cs\$(AssemblyName).resources.dll">
        <TargetPath>cs</TargetPath>
    </BuildOutputInPackage>
  </ItemGroup>
</Target>

TargetsForTfmSpecificContentInPackage

Scrivere una destinazione personalizzata e specificarla come valore della $(TargetsForTfmSpecificContentInPackage) proprietà . Per includere i file nel pacchetto, la destinazione deve scrivere tali file in ItemGroup TfmSpecificPackageFile e impostare i metadati facoltativi seguenti:

• PackagePath: percorso in cui deve essere restituito il file nel pacchetto. NuGet genera un avviso se più file vengono aggiunti allo stesso percorso del pacchetto.
• BuildAction: azione di compilazione da assegnare al file, obbligatoria solo se il percorso del pacchetto si trova nella contentFiles cartella . Il valore predefinito è "Nessuno".

Ad esempio,

<PropertyGroup>
  <TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);CustomContentTarget</TargetsForTfmSpecificContentInPackage>
</PropertyGroup>

<Target Name="CustomContentTarget">
  <ItemGroup>
    <TfmSpecificPackageFile Include="abc.txt">
      <PackagePath>mycontent/$(TargetFramework)</PackagePath>
    </TfmSpecificPackageFile>
    <TfmSpecificPackageFile Include="Extensions/ext.txt" Condition="'$(TargetFramework)' == 'net46'">
      <PackagePath>net46content</PackagePath>
    </TfmSpecificPackageFile>  
  </ItemGroup>
</Target>  

Destinazione restore

MSBuild -t:restore (usato da nuget restore e dotnet restore con progetti .NET Core) consente di ripristinare i pacchetti a cui si fa riferimento nel file di progetto, come segue:

1. Lettura di tutti i riferimenti da progetto a progetto
2. Lettura delle proprietà del progetto per trovare la cartella intermedia e i framework di destinazione
3. Passare MSBuild i dati a NuGet. Build.Tasks.dll
4. Esecuzione di restore
5. Download dei pacchetti
6. Scrittura dei file di asset, delle destinazioni e delle proprietà

La restore destinazione funziona per i progetti usando il formato PackageReference. MSBuild 16.5+ ha anche il supporto esplicito per il packages.config formato.

Ripristino delle proprietà

Le impostazioni di ripristino aggiuntive possono provenire da MSBuild proprietà nel file di progetto. I valori possono essere impostati anche dalla riga di comando tramite l'opzione -p: (vedere gli esempi riportati di seguito).

La ExcludeRestorePackageImports proprietà è una proprietà interna utilizzata da NuGet. Non deve essere modificato o impostato in alcun MSBuild file.

Esempi

Riga di comando:

msbuild -t:restore -p:RestoreConfigFile=<path>

File di progetto:

<PropertyGroup>
    <RestoreIgnoreFailedSources>true</RestoreIgnoreFailedSources>
</PropertyGroup>

Output del ripristino

Il ripristino crea i file seguenti nella cartella obj di compilazione:

Ripristino e compilazione con un MSBuild unico comando

A causa del fatto che NuGet è possibile ripristinare i pacchetti che causano MSBuild destinazioni e proprietà, le valutazioni di ripristino e compilazione vengono eseguite con proprietà globali diverse. Ciò significa che quanto segue avrà un comportamento imprevedibile e spesso errato.

msbuild -t:restore,build

L'approccio consigliato è invece:

msbuild -t:build -restore

La stessa logica si applica ad altre destinazioni simili a build.

Ripristino di progetti PackageReference e packages.config con MSBuild

Con MSBuild la versione 16.5+, packages.config è supportato anche per msbuild -t:restore.

msbuild -t:restore -p:RestorePackagesConfig=true

Ripristino con MSBuild valutazione del grafo statico

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

In alternativa, è possibile abilitarla impostando la proprietà in un oggetto Directory.Build.Props.

<Project>
  <PropertyGroup>
    <RestoreUseStaticGraphEvaluation>true</RestoreUseStaticGraphEvaluation>
  </PropertyGroup>
</Project>

Il ripristino statico del grafo modifica la msbuild parte del ripristino, la lettura e la valutazione del progetto, ma non l'algoritmo di ripristino. L'algoritmo di ripristino è lo stesso in tutti gli NuGet strumenti (NuGet.exe, MSBuild.exe, dotnet.exe e Visual Studio).

In pochissimi scenari, il ripristino statico del grafico può comportarsi in modo diverso rispetto al ripristino corrente e alcuni packageReference dichiarati o ProjectReference potrebbero non essere presenti.

Per semplificare la mente, come controllo una sola volta, quando si esegue la migrazione al ripristino statico del grafo, prendere in considerazione l'esecuzione:

msbuild.exe -t:restore -p:RestoreUseStaticGraphEvaluation=true
msbuild.exe -t:restore

NuGetnon deve segnalare alcuna modifica. Se viene visualizzata una discrepanza, inviare un problema in NuGet/Home.

Sostituzione di una libreria da un grafico di ripristino

Se un ripristino restituisce l'assembly errato, è possibile escludere la scelta predefinita di tali pacchetti e sostituirla con la propria scelta. Prima di tutto, con un PackageReference di livello superiore, escludere tutti gli asset:

<PackageReference Include="Newtonsoft.Json" Version="9.0.1">
  <ExcludeAssets>All</ExcludeAssets>
</PackageReference>

Aggiungere quindi il riferimento personalizzato alla copia locale appropriata della DLL:

<Reference Include="Newtonsoft.Json.dll" />