NuGet kemas dan pulihkan sebagai MSBuild target

  • Artikel

NuGet 4.0+

Dengan format PackageReference, NuGet 4.0+ dapat menyimpan semua metadata manifes langsung dalam file proyek daripada menggunakan file terpisah.nuspec.

Dengan MSBuild 15.1+, NuGet juga merupakan warga negara kelas MSBuild satu dengan pack target dan restore seperti yang dijelaskan di bawah ini. Target ini memungkinkan Anda untuk bekerja dengan NuGet seperti yang Anda lakukan dengan tugas atau target lainnya MSBuild . Untuk instruksi membuat NuGet paket menggunakan MSBuild, lihat Membuat NuGet paket menggunakan MSBuild. (Untuk NuGet 3.x dan yang lebih lama, Anda menggunakan perintah paket dan pemulihan melalui CLI sebagai gantinya NuGet .)

Urutan build target

Karena pack dan restore merupakan MSBuild target, Anda dapat mengaksesnya untuk meningkatkan alur kerja Anda. Misalnya, Anda ingin menyalin paket Anda ke berbagi jaringan setelah mengemasnya. Anda bisa melakukannya dengan menambahkan yang berikut ini di file proyek Anda:

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

Demikian pula, Anda dapat menulis MSBuild tugas, menulis target Anda sendiri dan menggunakan NuGet properti dalam MSBuild tugas.

Catatan

$(OutputPath) relatif dan mengharapkan bahwa Anda menjalankan perintah dari akar proyek.

target paket

Untuk proyek .NET yang menggunakan PackageReference format , menggunakan msbuild -t:pack gambar input dari file proyek untuk digunakan dalam membuat NuGet paket.

Tabel berikut ini menjelaskan MSBuild properti yang dapat ditambahkan ke file proyek dalam simpul pertama <PropertyGroup> . Anda dapat melakukan pengeditan ini dengan mudah di Visual Studio 2017 dan yang lebih baru dengan mengklik kanan proyek dan memilih Edit {project_name} pada menu konteks. Untuk kenyamanan, tabel diatur oleh properti yang setara dalam .nuspec file.

Catatan

Owners dan Summary properti dari .nuspec tidak didukung dengan MSBuild.

Atribut/nuspec Nilai MSBuild Properti Default Catatan
Id PackageId $(AssemblyName) $(AssemblyName) Dari MSBuild
Version PackageVersion Versi Ini kompatibel dengan semver, misalnya 1.0.0, , 1.0.0-betaatau 1.0.0-beta-00345. Default ke Version jika tidak diatur.
VersionPrefix VersionPrefix kosong Penimpaan pengaturan PackageVersionVersionPrefix
VersionSuffix VersionSuffix kosong Penimpaan pengaturan PackageVersionVersionSuffix
Authors Authors Nama pengguna pengguna saat ini Daftar penulis paket yang dipisahkan titik koma, cocok dengan nama profil di nuget.org. Ini ditampilkan di NuGet Galeri pada nuget.org dan digunakan untuk paket referensi silang oleh penulis yang sama.
Owners T/A Tidak ada di nuspec
Title Title $(PackageId) Judul paket yang ramah manusia, biasanya digunakan dalam tampilan UI seperti pada nuget.org dan Manajer Paket di Visual Studio.
Description Description "Deskripsi Paket" Deskripsi panjang untuk perakitan. Jika PackageDescription tidak ditentukan, maka properti ini juga digunakan sebagai deskripsi paket.
Copyright Copyright kosong Detail hak cipta untuk paket.
RequireLicenseAcceptance PackageRequireLicenseAcceptance false Nilai Boolean yang menentukan apakah klien harus meminta konsumen untuk menerima lisensi paket sebelum menginstal paket.
license PackageLicenseExpression kosong <license type="expression">Sesuai dengan . Lihat Mengemas ekspresi lisensi atau file lisensi.
license PackageLicenseFile kosong Jalur ke file lisensi dalam paket jika Anda menggunakan lisensi kustom atau lisensi yang belum ditetapkan pengidentifikasi SPDX. Anda perlu mengemas file lisensi yang dirujuk secara eksplisit. <license type="file">Sesuai dengan . Lihat Mengemas ekspresi lisensi atau file lisensi.
LicenseUrl PackageLicenseUrl kosong PackageLicenseUrl tidak digunakan lagi. Gunakan PackageLicenseExpression atau PackageLicenseFile sebagai gantinya.
ProjectUrl PackageProjectUrl kosong
Icon PackageIcon kosong Jalur ke gambar dalam paket untuk digunakan sebagai ikon paket. Anda perlu mengemas file gambar ikon yang dirujuk secara eksplisit. Untuk informasi selengkapnya, lihat Mengemas file gambar ikon dan icon metadata.
IconUrl PackageIconUrl kosong PackageIconUrl tidak digunakan lagi dan digantikan dengan PackageIcon. Namun, untuk pengalaman downlevel terbaik, Anda harus menentukan PackageIconUrl selain PackageIcon.
Readme PackageReadmeFile kosong Anda perlu mengemas file readme yang dirujuk secara eksplisit.
Tags PackageTags kosong Daftar tag yang dibatasi titik koma yang menunjuk paket.
ReleaseNotes PackageReleaseNotes kosong Catatan rilis untuk paket.
Repository/Url RepositoryUrl kosong URL repositori yang digunakan untuk mengkloning atau mengambil kode sumber. Contoh: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git.
Repository/Type RepositoryType kosong Jenis repositori. Contoh: git (default), tfs.
Repository/Branch RepositoryBranch kosong Informasi cabang repositori opsional. RepositoryUrl juga harus ditentukan agar properti ini disertakan. Contoh: master (NuGet 4.7.0+).
Repository/Commit RepositoryCommit kosong Penerapan atau set perubahan repositori opsional untuk menunjukkan sumber mana yang dibangun oleh paket. RepositoryUrl juga harus ditentukan agar properti ini disertakan. Contoh: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+).
PackageType <PackageType>CustomType1, 1.0.0.0;CustomType2</PackageType> Menunjukkan penggunaan paket yang dimaksudkan. Jenis paket menggunakan format yang sama dengan ID paket dan dibatasi oleh ;. Jenis paket dapat diberi versi dengan menambahkan , dan string Version . Lihat Mengatur NuGet jenis paket (NuGet 3.5.0+).
Summary Tidak didukung

input target paket

Properti Deskripsi
IsPackable Nilai Boolean yang menentukan apakah proyek dapat dikemas. Nilai defaultnya adalah true.
SuppressDependenciesWhenPacking Atur ke true untuk menekan dependensi paket dari paket yang dihasilkan NuGet .
PackageVersion Menentukan versi yang akan dimiliki paket yang dihasilkan. Menerima semua bentuk NuGet string versi. Defaultnya adalah nilai $(Version), yaitu, dari properti Version dalam proyek.
PackageId Menentukan nama untuk paket yang dihasilkan. Jika tidak ditentukan, pack operasi akan default menggunakan AssemblyName nama direktori atau sebagai nama paket.
PackageDescription Deskripsi panjang paket untuk tampilan UI.
Authors Daftar penulis paket yang dipisahkan titik koma, cocok dengan nama profil di nuget.org. Ini ditampilkan di NuGet Galeri pada nuget.org dan digunakan untuk paket referensi silang oleh penulis yang sama.
Description Deskripsi panjang untuk perakitan. Jika PackageDescription tidak ditentukan, maka properti ini juga digunakan sebagai deskripsi paket.
Copyright Detail hak cipta untuk paket.
PackageRequireLicenseAcceptance Nilai Boolean yang menentukan apakah klien harus meminta konsumen untuk menerima lisensi paket sebelum menginstal paket. Default adalah false.
DevelopmentDependency Nilai Boolean yang menentukan apakah paket ditandai sebagai dependensi khusus pengembangan, yang mencegah paket disertakan sebagai dependensi dalam paket lain. Dengan PackageReference (NuGet 4.8+), bendera ini juga berarti bahwa aset waktu kompilasi dikecualikan dari kompilasi. Untuk informasi selengkapnya, lihat Dukungan DevelopmentDependency untuk PackageReference.
PackageLicenseExpression Pengidentifikasi atau ekspresi lisensi SPDX, misalnya, Apache-2.0. Untuk informasi selengkapnya, lihat Mengemas ekspresi lisensi atau file lisensi.
PackageLicenseFile Jalur ke file lisensi dalam paket jika Anda menggunakan lisensi kustom atau lisensi yang belum ditetapkan pengidentifikasi SPDX.
PackageLicenseUrl PackageLicenseUrl tidak digunakan lagi. Gunakan PackageLicenseExpression atau PackageLicenseFile sebagai gantinya.
PackageProjectUrl
PackageIcon Menentukan jalur ikon paket, relatif terhadap akar paket. Untuk informasi selengkapnya, lihat Mengemas file gambar ikon.
PackageReleaseNotes Catatan rilis untuk paket.
PackageReadmeFile Readme untuk paket.
PackageTags Daftar tag yang dibatasi titik koma yang menunjuk paket.
PackageOutputPath Menentukan jalur output tempat paket yang dikemas akan dihilangkan. Defaultnya adalah $(OutputPath).
IncludeSymbols Nilai Boolean ini menunjukkan apakah paket harus membuat paket simbol tambahan saat proyek dikemas. Format paket simbol dikontrol oleh SymbolPackageFormat properti . Untuk informasi selengkapnya, lihat IncludeSymbols.
IncludeSource Nilai Boolean ini menunjukkan apakah proses paket harus membuat paket sumber. Paket sumber berisi kode sumber pustaka serta file PDB. File sumber diletakkan di bawah src/ProjectName direktori dalam file paket yang dihasilkan. Untuk informasi selengkapnya, lihat IncludeSource.
PackageType
IsTool Menentukan apakah semua file output disalin ke folder alat alih-alih folder lib . Untuk informasi selengkapnya, lihat IsTool.
RepositoryUrl URL repositori yang digunakan untuk mengkloning atau mengambil kode sumber. Contoh: https://github.com/NuGethttps://github.com/NuGet/NuGet.Client.git.
RepositoryType Jenis repositori. Contoh: git (default), tfs.
RepositoryBranch Informasi cabang repositori opsional. RepositoryUrl juga harus ditentukan agar properti ini disertakan. Contoh: master (NuGet 4.7.0+).
RepositoryCommit Penerapan atau set perubahan repositori opsional untuk menunjukkan sumber mana yang dibangun oleh paket. RepositoryUrl juga harus ditentukan agar properti ini disertakan. Contoh: 0e4d1b598f350b3dc675018d539114d1328189ef (NuGet 4.7.0+).
SymbolPackageFormat Menentukan format paket simbol. Jika "symbols.nupkg", paket simbol warisan dibuat dengan ekstensi .symbols.nupkg yang berisi PDB, DLL, dan file output lainnya. Jika "snupkg", paket simbol snupkg dibuat yang berisi PDB portabel. Defaultnya adalah "symbols.nupkg".
NoPackageAnalysis Menentukan bahwa pack tidak boleh menjalankan analisis paket setelah membuat paket.
MinClientVersion Menentukan versi NuGet minimum klien yang dapat menginstal paket ini, yang diberlakukan oleh nuget.exe dan Manajer Paket Visual Studio.
IncludeBuildOutput Nilai Boolean ini menentukan apakah rakitan output build harus dikemas ke dalam file .nupkg atau tidak.
IncludeContentInPack Nilai Boolean ini menentukan apakah ada item yang memiliki jenis Content yang disertakan dalam paket yang dihasilkan secara otomatis. Default adalah true.
BuildOutputTargetFolder Menentukan folder tempat menempatkan rakitan output. Rakitan output (dan file output lainnya) disalin ke dalam folder kerangka kerja masing-masing. Untuk informasi selengkapnya, lihat Rakitan output.
ContentTargetFolders Menentukan lokasi default tempat semua file konten harus pergi jika PackagePath tidak ditentukan untuk file tersebut. Nilai defaultnya adalah "konten; contentFiles". Untuk informasi selengkapnya, lihat Menyertakan konten dalam paket.
NuspecFile Jalur relatif atau absolut ke file yang .nuspec digunakan untuk pengemasan. Jika ditentukan, ini digunakan secara eksklusif untuk informasi pengemasan, dan informasi apa pun dalam proyek tidak digunakan. Untuk informasi selengkapnya, lihat Pengemasan menggunakan .nuspec.
NuspecBasePath Jalur dasar untuk .nuspec file. Untuk informasi selengkapnya, lihat Pengemasan menggunakan .nuspec.
NuspecProperties Daftar pasangan key=value yang dipisahkan titik koma. Untuk informasi selengkapnya, lihat Pengemasan menggunakan .nuspec.

skenario paket

Menekan dependensi

Untuk menekan dependensi paket dari paket yang dihasilkan NuGet , atur SuppressDependenciesWhenPacking ke true yang akan memungkinkan melompati semua dependensi dari file nupkg yang dihasilkan.

PackageIconUrl

PackageIconUrl tidak digunakan lagi demi PackageIcon properti. Dimulai dengan NuGet 5.3 dan Visual Studio 2019 versi 16.3, pack meningkatkan peringatan NU5048 jika metadata paket hanya menentukan PackageIconUrl.

PackageIcon

Tip

Untuk mempertahankan kompatibilitas mundur dengan klien dan sumber yang belum mendukung PackageIcon, tentukan dan PackageIconPackageIconUrl. Visual Studio mendukung PackageIcon paket yang berasal dari sumber berbasis folder.

Mengemas file gambar ikon

Saat mengemas file gambar ikon, gunakan PackageIcon properti untuk menentukan jalur file ikon, relatif terhadap akar paket. Selain itu, pastikan bahwa file disertakan dalam paket. Ukuran file gambar dibatasi hingga 1 MB. Format file yang didukung mencakup JPEG dan PNG. Kami merekomendasikan resolusi gambar 128x128.

Contohnya:

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

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

Sampel Ikon Paket.

Untuk yang nuspec setara, lihat nuspec referensi untuk ikon.

PackageReadmeFile

Didukung dengan NuGet pratinjau 5.10.0 2.NET / SDK 5.0.300 ke atas

Saat mengemas file readme, Anda perlu menggunakan PackageReadmeFile properti untuk menentukan jalur paket, relatif terhadap akar paket. Selain itu, Anda perlu memastikan bahwa file disertakan dalam paket. Format file yang didukung hanya menyertakan Markdown (.md).

Contohnya:

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

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

Untuk yang nuspec setara, lihat nuspec referensi untuk readme.

Rakitan output

nuget packmenyalin file output dengan ekstensi .exe, , .dll, .xml, .winmd.json, dan .pri. File output yang disalin bergantung pada apa yang MSBuild disediakan dari BuiltOutputProjectGroup target.

Ada dua MSBuild properti yang dapat Anda gunakan dalam file proyek atau baris perintah untuk mengontrol ke mana assembly output pergi:

  • IncludeBuildOutput: Boolean yang menentukan apakah rakitan output build harus disertakan dalam paket.
  • BuildOutputTargetFolder: Menentukan folder tempat rakitan output harus ditempatkan. Rakitan output (dan file output lainnya) disalin ke dalam folder kerangka kerja masing-masing.

Referensi paket

Lihat Referensi Paket di File Proyek.

Proyek ke referensi proyek

Referensi proyek ke proyek dianggap secara default sebagai NuGet referensi paket. Contohnya:

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

Anda juga dapat menambahkan metadata berikut ke referensi proyek Anda:

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Menyertakan konten dalam paket

Untuk menyertakan konten, tambahkan metadata tambahan ke item yang <Content> sudah ada. Secara default, semua jenis "Konten" disertakan dalam paket kecuali Anda mengambil alih dengan entri seperti berikut:

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

Secara default, semuanya ditambahkan ke akar content folder dan contentFiles\any\<target_framework> dalam paket dan mempertahankan struktur folder relatif, kecuali Anda menentukan jalur paket:

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

Jika Anda ingin menyalin semua konten Anda hanya ke folder akar tertentu (bukan content dan contentFiles keduanya), Anda dapat menggunakan MSBuild properti ContentTargetFolders, yang defaultnya ke "konten; contentFiles" tetapi dapat diatur ke nama folder lainnya. Perhatikan bahwa hanya menentukan "contentFiles" dalam ContentTargetFolders menempatkan file di bawah contentFiles\any\<target_framework> atau contentFiles\<language>\<target_framework> berdasarkan buildAction.

PackagePath dapat berupa sekumpulan jalur target yang dibatasi titik koma. Menentukan jalur paket kosong akan menambahkan file ke akar paket. Misalnya, berikut ini menambahkan libuv.txt ke content\myfiles, content\samples, dan akar paket:

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

Ada juga MSBuild properti $(IncludeContentInPack), yang default ke true. Jika ini diatur ke false pada proyek apa pun, maka konten dari proyek tersebut tidak termasuk dalam paket nuget.

Metadata spesifik paket lain yang dapat Anda atur pada salah satu item di atas termasuk dan set dan nilai mana pada contentFiles entri dalam output nuspec.FlattenCopyToOutput<PackageFlatten><PackageCopyToOutput>

Catatan

Selain item Konten, <Pack> metadata dan <PackagePath> juga dapat diatur pada file dengan tindakan build Compile, EmbeddedResource, ApplicationDefinition, Page, Resource, SplashScreen, DesignData, DesignDataWithDesignTimeCreateableTypes, CodeAnalysisDictionary, AndroidAsset, AndroidResource, BundleResource atau None.

Agar paket menambahkan nama file ke jalur paket Anda saat menggunakan pola globbing, jalur paket Anda harus diakhir dengan karakter pemisah folder, jika tidak, jalur paket diperlakukan sebagai jalur lengkap termasuk nama file.

SertakanSymbols

Saat menggunakan MSBuild -t:pack -p:IncludeSymbols=true, file yang sesuai .pdb disalin bersama dengan file output lainnya (.dll, , .exe, .winmd.xml, .json, .pri). Perhatikan bahwa pengaturan IncludeSymbols=true membuat paket reguler dan paket simbol.

IncludeSource

Ini sama IncludeSymbolsdengan , kecuali menyalin file sumber bersama dengan .pdb file juga. Semua file jenis Compile disalin untuk src\<ProjectName>\ mempertahankan struktur folder jalur relatif dalam paket yang dihasilkan. Hal yang sama juga terjadi untuk file sumber yang ProjectReference telah TreatAsPackageReference diatur ke false.

Jika file jenis Kompilasi, berada di luar folder proyek, maka file hanya ditambahkan ke src\<ProjectName>\.

Mengemas ekspresi lisensi atau file lisensi

Saat menggunakan ekspresi lisensi, gunakan PackageLicenseExpression properti . Untuk sampel, lihat Sampel ekspresi lisensi.

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

Untuk mempelajari selengkapnya tentang ekspresi lisensi dan lisensi yang diterima oleh NuGet.org, lihat metadata lisensi.

Saat mengemas file lisensi, gunakan PackageLicenseFile properti untuk menentukan jalur paket, relatif terhadap akar paket. Selain itu, pastikan bahwa file disertakan dalam paket. Contohnya:

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

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

Untuk sampel, lihat Sampel file lisensi.

Catatan

Hanya satu dari PackageLicenseExpression, PackageLicenseFile, dan PackageLicenseUrl yang dapat ditentukan pada satu waktu.

Mengemas file tanpa ekstensi

Dalam beberapa skenario, seperti saat mengemas file lisensi, Anda mungkin ingin menyertakan file tanpa ekstensi. Untuk alasan historis, NuGet & MSBuild perlakukan jalur tanpa ekstensi sebagai direktori.

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

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

File tanpa sampel ekstensi.

IsTool

Saat menggunakan MSBuild -t:pack -p:IsTool=true, semua file output, seperti yang ditentukan dalam skenario Output Assemblies , disalin ke tools folder alih-alih lib folder. Perhatikan bahwa ini berbeda dari yang DotNetCliTool ditentukan dengan mengatur PackageType dalam .csproj file.

Pengemasan menggunakan .nuspec file

Meskipun disarankan agar Anda menyertakan semua properti yang biasanya ada dalam .nuspec file dalam file proyek, Anda dapat memilih untuk menggunakan .nuspec file untuk mengemas proyek Anda. Untuk proyek gaya non-SDK yang menggunakan PackageReference, Anda harus mengimpor NuGet.Build.Tasks.Pack.targets sehingga tugas paket dapat dijalankan. Anda masih perlu memulihkan proyek sebelum dapat mengemas nuspec file. (Proyek bergaya SDK menyertakan target paket secara default.)

Kerangka kerja target file proyek tidak relevan dan tidak digunakan saat mengemas nuspec. Tiga MSBuild properti berikut relevan dengan pengemasan menggunakan .nuspec:

  1. NuspecFile: jalur relatif atau absolut ke file yang .nuspec digunakan untuk pengemasan.
  2. NuspecProperties: daftar pasangan key=value yang dipisahkan titik koma. Karena cara MSBuild kerja penguraian baris perintah, beberapa properti harus ditentukan sebagai berikut: -p:NuspecProperties="key1=value1;key2=value2".
  3. NuspecBasePath: Jalur dasar untuk .nuspec file.

Jika menggunakan dotnet.exe untuk mengemas proyek Anda, gunakan perintah seperti berikut ini:

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

Jika menggunakan MSBuild untuk mengemas proyek Anda, gunakan perintah seperti berikut ini:

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

Harap dicatat bahwa mengemas nuspec menggunakan dotnet.exe atau msbuild juga menyebabkan pembangunan proyek secara default. Ini dapat dihindari dengan meneruskan --no-build properti ke dotnet.exe, yang setara dengan pengaturan <NoBuild>true</NoBuild> dalam file proyek Anda, bersama dengan pengaturan <IncludeBuildOutput>false</IncludeBuildOutput> dalam file proyek.

Contoh file .csproj untuk mengemas nuspec file adalah:

<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>

Titik ekstensi tingkat lanjut untuk membuat paket yang disesuaikan

Target pack menyediakan dua titik ekstensi yang berjalan di build spesifik kerangka kerja target dalam. Dukungan titik ekstensi termasuk konten dan rakitan khusus kerangka kerja target ke dalam paket:

  • TargetsForTfmSpecificBuildOutput target: Gunakan untuk file di lib dalam folder atau folder yang ditentukan menggunakan BuildOutputTargetFolder.
  • TargetsForTfmSpecificContentInPackage target: Gunakan untuk file di BuildOutputTargetFolderluar .

TargetsForTfmSpecificBuildOutput

Tulis target kustom dan tentukan sebagai nilai $(TargetsForTfmSpecificBuildOutput) properti . Untuk file apa pun yang perlu masuk ke BuildOutputTargetFolder (lib secara default), target harus menulis file tersebut ke dalam ItemGroup BuildOutputInPackage dan mengatur dua nilai metadata berikut:

  • FinalOutputPath: Jalur absolut file; jika tidak disediakan, Identitas digunakan untuk mengevaluasi jalur sumber.
  • TargetPath: (Opsional) Atur ketika file perlu masuk ke subfolder dalam lib\<TargetFramework> , seperti rakitan satelit yang berada di bawah folder budaya masing-masing. Default ke nama file.

Contoh:

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

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

TargetsForTfmSpecificContentInPackage

Tulis target kustom dan tentukan sebagai nilai $(TargetsForTfmSpecificContentInPackage) properti . Agar file apa pun disertakan dalam paket, target harus menulis file tersebut ke dalam ItemGroup TfmSpecificPackageFile dan mengatur metadata opsional berikut:

  • PackagePath: Jalur tempat file harus keluaran dalam paket. NuGet mengeluarkan peringatan jika lebih dari satu file ditambahkan ke jalur paket yang sama.
  • BuildAction: Tindakan build untuk ditetapkan ke file, hanya diperlukan jika jalur paket ada di contentFiles folder . Default ke "Tidak Ada".

Contoh:

<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>

pulihkan target

MSBuild -t:restore (yang nuget restore dan dotnet restore menggunakan dengan proyek .NET Core), memulihkan paket yang dirujuk dalam file proyek sebagai berikut:

  1. Membaca semua referensi proyek ke proyek
  2. Membaca properti proyek untuk menemukan folder perantara dan kerangka kerja target
  3. Teruskan MSBuild data ke NuGet. Build.Tasks.dll
  4. Jalankan pemulihan
  5. Mengunduh paket
  6. Menulis file aset, target, dan alat peraga

Target restore berfungsi untuk proyek menggunakan format PackageReference. MSBuild 16.5+juga memiliki dukungan keikutsertaan untuk format .packages.config

Catatan

restore Target tidak boleh dijalankan dalam kombinasi dengan build target.

Pulihkan properti

Pengaturan pemulihan tambahan mungkin berasal dari MSBuild properti dalam file proyek. Nilai juga dapat diatur dari baris perintah menggunakan sakelar -p: (lihat Contoh di bawah).

Properti Deskripsi
RestoreSources Daftar sumber paket yang dibatasi titik koma.
RestorePackagesPath Jalur folder paket pengguna.
RestoreDisableParallel Batasi unduhan satu per satu.
RestoreConfigFile Jalur ke file yang Nuget.Config akan diterapkan.
RestoreNoHttpCache Jika true, hindari menggunakan paket http cache. Lihat Mengelola paket global dan folder cache.
RestoreIgnoreFailedSources Jika true, mengabaikan sumber paket yang gagal atau hilang.
RestoreFallbackFolders Folder fallback, digunakan dengan cara yang sama seperti folder paket pengguna digunakan.
RestoreAdditionalProjectSources Sumber tambahan untuk digunakan selama pemulihan.
RestoreAdditionalProjectFallbackFolders Folder fallback tambahan untuk digunakan selama pemulihan.
RestoreAdditionalProjectFallbackFoldersExcludes Mengecualikan folder fallback yang ditentukan dalam RestoreAdditionalProjectFallbackFolders
RestoreTaskAssemblyFile Jalur ke NuGet.Build.Tasks.dll.
RestoreGraphProjectInput Daftar proyek yang dibatasi titik koma untuk dipulihkan, yang harus berisi jalur absolut.
RestoreUseSkipNonexistentTargets Ketika proyek dikumpulkan melaluinya MSBuild menentukan apakah proyek dikumpulkan menggunakan pengoptimalan SkipNonexistentTargets . Ketika tidak diatur, default ke true. Konsekuensinya adalah perilaku gagal cepat ketika target proyek tidak dapat diimpor.
MSBuildProjectExtensionsPath Folder output, default ke BaseIntermediateOutputPath dan obj folder .
RestoreForce Dalam proyek berbasis PackageReference, memaksa semua dependensi diselesaikan meskipun pemulihan terakhir berhasil. Menentukan bendera ini mirip dengan menghapus project.assets.json file. Ini tidak melewati http-cache.
RestorePackagesWithLockFile Memilih penggunaan file kunci.
RestoreLockedMode Jalankan pemulihan dalam mode terkunci. Ini berarti bahwa pemulihan tidak akan mengevaluasi ulang dependensi.
NuGetLockFilePath Lokasi kustom untuk file kunci. Lokasi default berada di samping proyek dan diberi nama packages.lock.json.
RestoreForceEvaluate Memaksa pemulihan untuk mengolah ulang dependensi dan memperbarui file kunci tanpa peringatan apa pun.
RestorePackagesConfig Sakelar keikutsertaan, yang memulihkan proyek dengan packages.config. Dukungan hanya dengan MSBuild -t:restore .
RestoreRepositoryPath packages.config saja. Menentukan direktori paket tempat paket harus dipulihkan. SolutionDirectory akan digunakan jika tidak ditentukan.
RestoreUseStaticGraphEvaluation Sakelar keikutsertaan untuk menggunakan evaluasi grafik MSBuild statis alih-alih evaluasi standar. Evaluasi grafik statis adalah fitur eksperimental yang secara signifikan lebih cepat untuk repositori dan solusi besar.

Properti ExcludeRestorePackageImports adalah properti internal yang digunakan oleh NuGet. Ini tidak boleh dimodifikasi atau diatur dalam file apa pun MSBuild .

Contoh

Baris perintah:

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

File proyek:

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

Pulihkan output

Pemulihan membuat file berikut di folder build obj :

File Deskripsi
project.assets.json Berisi grafik dependensi dari semua referensi paket.
{projectName}.projectFileExtension.nuget.g.props Referensi ke MSBuild alat peraga yang terkandung dalam paket
{projectName}.projectFileExtension.nuget.g.targets Referensi ke MSBuild target yang terkandung dalam paket

Memulihkan dan membangun dengan satu MSBuild perintah

Karena fakta bahwa NuGet dapat memulihkan paket yang menurunkan MSBuild target dan alat peraga, evaluasi pemulihan dan build dijalankan dengan properti global yang berbeda. Ini berarti bahwa berikut ini akan memiliki perilaku yang tidak dapat diprediksi dan sering salah.

msbuild -t:restore,build

Sebagai gantinya, pendekatan yang direkomendasikan adalah:

msbuild -t:build -restore

Logika yang sama berlaku untuk target lain yang mirip builddengan .

Memulihkan proyek PackageReference dan packages.config dengan MSBuild

Dengan MSBuild 16.5+, packages.config juga didukung untuk msbuild -t:restore.

msbuild -t:restore -p:RestorePackagesConfig=true

Catatan

packages.config pemulihan hanya tersedia dengan MSBuild 16.5+, dan tidak dengan dotnet.exe

Memulihkan dengan MSBuild evaluasi grafik statis

Catatan

Dengan MSBuild 16.6+, NuGet telah menambahkan fitur eksperimental untuk menggunakan evaluasi grafik statis dari baris perintah yang secara signifikan meningkatkan waktu pemulihan untuk repositori besar.

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

Atau Anda dapat mengaktifkannya dengan mengatur properti di Directory.Build.Props.

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

Catatan

Pada Visual Studio 2019.x dan NuGet 5.x, fitur ini dianggap eksperimental dan ikut serta. Ikuti NuGet/Home#9803 untuk detail tentang kapan fitur ini akan diaktifkan secara default.

Pemulihan grafik statis mengubah bagian pemulihan msbuild, pembacaan dan evaluasi proyek, tetapi bukan algoritma pemulihan! Algoritma pemulihan sama di semua NuGet alat (NuGet.exe, MSBuild.exe, dotnet.exe, dan Visual Studio).

Dalam skenario yang sangat sedikit, pemulihan grafik statis mungkin berperilaku berbeda dari pemulihan saat ini dan PackageReferences atau ProjectReferences tertentu yang dinyatakan mungkin hilang.

Untuk memudahkan pikiran Anda, sebagai pemeriksaan satu kali, saat bermigrasi ke pemulihan grafik statis, pertimbangkan untuk menjalankan:

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

NuGettidak boleh melaporkan perubahan apa pun. Jika Anda melihat perbedaan, silakan ajukan masalah di NuGet/Home.

Mengganti satu pustaka dari grafik pemulihan

Jika pemulihan membawa rakitan yang salah, dimungkinkan untuk mengecualikan pilihan default paket tersebut, dan menggantinya dengan pilihan Anda sendiri. Pertama dengan tingkat PackageReferenceatas , kecualikan semua aset:

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

Selanjutnya, tambahkan referensi Anda sendiri ke salinan dll lokal yang sesuai:

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