NuGet hedef olarak paketleme MSBuild ve geri yükleme

4.0+

PackageReference biçimiyle, 4.0+ tüm bildirim meta verilerini ayrı bir dosya kullanmak yerine doğrudan bir proje dosyasında .nuspec depolar.

15.1+ ile, ayrıca aşağıda açıklandığı gibi ve hedeflerine sahip MSBuild birinci NuGet sınıf bir MSBuildpackrestore vatandaştır. Bu hedefler, diğer görev veya hedeflerle olduğu gibi NuGetMSBuild çalışmanız için size olanak sağlar. kullanarak paket oluşturma NuGet yönergeleri için MSBuild bkz. Create a NuGet package using MSBuild . (Için NuGet 3.x ve önceki sürümler için, cli NuGetpaketi ve geri yükleme komutlarını kullanırsınız.)

Hedef derleme sırası

packve restore hedef olduğundan iş MSBuild akışınızı geliştirmek için bu hedeflere erişebilirsiniz. Örneğin, paketinizi paketledikten sonra bir ağ paylaşımına kopyalamak istediğinizi diyelim. Proje dosyanıza şunları ekleyerek bunu yapabilirsiniz:

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

Benzer şekilde, bir görev MSBuild yazabilir, kendi hedefinizi yazabilir ve NuGet görev özelliklerini MSBuild tüketebilirsiniz.

paket hedefi

biçimini kullanan .NET projeleri için, kullanılarak paket PackageReferencemsbuild -t:pack oluşturmada kullanmak üzere proje dosyasından girişler NuGet çizer.

Aşağıdaki tabloda, ilk MSBuild düğüm içindeki bir proje dosyasına eklenilen özellikler <PropertyGroup> açıklenmiştir. Projeye sağ tıklar ve bağlam menüsünde Düzenle {project_name} öğesini seçerek bu düzenlemeleri 2017 ve sonraki bir Visual Studio kolayca yapabilirsiniz. Kolaylık olması için tablo, " " data-linktype="relative-path">dosyasındaki eşdeğer özelliğine .nuspec göre düzenlenmiştir.

paket hedefi girişleri

paket senaryoları

Gizleme bağımlılıkları

Oluşturulan paketten paket bağımlılıklarını bastırmak için NuGet , olarak ayarlayın SuppressDependenciesWhenPacking ve true oluşturulan nupkg dosyasından tüm bağımlılıkların atlanmasını sağlar.

PackageIconUrl

PackageIconUrl özelliği kullanım dışı bırakılmıştır PackageIcon . NuGet5,3 ve Visual Studio 2019 sürüm 16,3 ' den başlayarak, pack paket meta verileri yalnızca belirtiyorsa NuGet uyarı oluşturur PackageIconUrl .

PackageIcon

Simge görüntüsü dosyası paketleme

Bir simge görüntü dosyası paketleme sırasında, PackageIcon paketin köküne göre simge dosya yolunu belirtmek için özelliğini kullanın. Ayrıca, dosyanın pakete eklendiğinden emin olun. Görüntü dosyası boyutu 1 MB ile sınırlıdır. Desteklenen dosya biçimleri JPEG ve PNG içerir. 128x128 görüntü çözümlemesi yapmanızı öneririz.

Örnek:

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

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

NuGet /samples/tree/main/packageiconexample "data-linktype =" external ">Package ıcon sample .

nuspecEşdeğer bir deyişle, nuspecnuspec simgenin "#icon" Data-LinkType = "göreli yol" başvurusuna göz atın >nuspec .

PackageReadmeFile

5.10.0 Preview 2.NET SDK 5.0.300 ve üstü ile desteklenir

Bir Benioku dosyası paketleme sırasında, paketin PackageReadmeFile köküne göre paket yolunu belirtmek için özelliğini kullanmanız gerekir. Buna ek olarak, dosyanın pakete eklendiğinden emin olmanız gerekir. Desteklenen dosya biçimleri yalnızca Marklt (. MD) içerir.

Örnek:

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

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

nuspecEşdeğer olarak, nuspecnuspec Benioku için "#readme" Data-LinkType = "göreli yol" başvurusuna göz atın >nuspec .

Çıkış derlemeleri

nuget pack çıktı dosyalarını,,,, ve uzantılarına kopyalar .exe.dll.xml.winmd.json.pri . Kopyalanan çıkış dosyaları MSBuild hedeften neler sundığına bağlıdır BuiltOutputProjectGroup .

MSBuildÇıktı derlemelerinin nerede olduğunu denetlemek için, proje dosyanızda veya komut satırında kullanabileceğiniz iki özellik vardır:

• IncludeBuildOutput: Derleme çıkış derlemelerinin pakete dahil edilip edilmeyeceğini belirleyen bir Boole değeri.
• BuildOutputTargetFolder: Çıkış derlemelerinin yerleştirilmesi gereken klasörü belirtir. Çıkış derlemeleri (ve diğer çıkış dosyaları) ilgili çerçeve klasörlerine kopyalanır.

Paket başvuruları

Project dosyalardaki paket başvurularınabakın.

proje başvurularına Project

proje başvurularına Project, varsayılan olarak NuGet paket başvuruları olarak değerlendirilir. Örnek:

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

Proje başvurunıza aşağıdaki meta verileri de eklemek için kullanabilirsiniz:

<IncludeAssets>
<ExcludeAssets>
<PrivateAssets>

Pakete içerik dahil

İçerik eklemek için var olan öğeye ek meta veriler <Content> ekleyin. Varsayılan olarak, aşağıdaki gibi girişlerle geçersiz kılmadıkça "İçerik" türüne sahip her şey pakete dahil edilir:

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

Varsayılan olarak, bir paket içindeki ve klasörünün köküne her şey eklenir ve bir paket yolu belirtmedikçe contentcontentFiles\any\<target_framework> göreli klasör yapısını korur:

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

Tüm içeriğinizi yalnızca belirli bir kök klasöre (ve her ikisi yerine) kopyalamak için varsayılan contentcontentFiles olarak MSBuild "content;contentFiles" özelliğini kullanabilirsiniz ancak başka bir klasör adı olarak ContentTargetFolders ayarlanabilirsiniz. yalnızca içinde "contentFiles" belirtildiğinde dosyaların ContentTargetFolders altına veya temel alarak koy olduğunu contentFiles\any\<target_framework>contentFiles\<language>\<target_framework>buildAction unutmayın.

PackagePath noktalı virgülle ayrılmış bir hedef yol kümesi olabilir. Boş bir paket yolu belirtmek dosyayı paketin köküne ekler. Örneğin, aşağıdaki , libuv.txtcontent\myfiles ve paket content\samples köküne ekler:

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

Ayrıca, varsayılan MSBuild olarak $(IncludeContentInPack) değerine sahip olan bir özelliği de true vardır. Bu herhangi bir false projede olarak ayarlanırsa, bu projeden içerik nuget paketine dahil değildir.

Yukarıdaki öğelerden herhangi biri üzerinde ayarlandırabilirsiniz diğer pakete özgü meta veriler, çıkışında girdisinde hangi kümeleri ve <PackageCopyToOutput><PackageFlatten> değerleri CopyToOutputFlattencontentFiles nuspec içerir.

IncludeSymbols

kullanılırken, karşılık gelen dosyalar diğer çıkış dosyalarıyla birlikte MSBuild -t:pack -p:IncludeSymbols=true.pdb kopyalanır ( , , .dll , , , .exe.winmd.xml.json.pri ). Ayarın normal IncludeSymbols=true bir paket ve bir semboller IncludeSymbols=true oluşturduğuna dikkat.

IncludeSource

Bu, ile aynıdır IncludeSymbols ancak kaynak dosyaları da dosyalarla birlikte .pdb kopyalar. Türünde tüm Compile dosyalar, sonuçta elde edilen src\<ProjectName>\ pakette göreli yol klasör yapısını korumak için üzerine kopyalanır. Aynı durum, olarak ayarlanmış herhangi bir kaynak ProjectReference dosya TreatAsPackageReference için de false gerçekleşir.

Derleme türünde bir dosya proje klasörünün dışında ise, yalnızca dosyasına src\<ProjectName>\ eklenir.

Lisans ifadesi veya lisans dosyası paketleme

Lisans ifadesi kullanırken özelliğini PackageLicenseExpression kullanın. Örnek için bkz. NuGet /Samples/tree/main/PackageLicenseExpressionExample" data-linktype="external">License ifadesi örneği.

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

.org tarafından kabul edilen lisans ifadeleri ve lisanslar hakkında daha fazla bilgi edinmek için NuGet bkz. NuGet " nuspec #license" data-linktype="relative-path">meta verileri.

Bir lisans dosyasını PackageLicenseFile paketlerken, paketin köküne göre paket yolunu belirtmek için özelliğini kullanın. Ayrıca, dosyanın pakete dahil olduğundan emin olun. Örnek:

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

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

Örnek için bkz. NuGet /Samples/tree/main/PackageLicenseFileExample" data-linktype="external">License file sample .

Uzantı olmadan dosya paketleme

Lisans dosyası paketleme gibi bazı senaryolarda, uzantı olmadan bir dosya eklemek istiyor olabilir. Geçmiş nedenlerle, NuGet&MSBuild uzantısız yolları dizin olarak ele atın.

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

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

NuGet /Samples/blob/main/PackageLicenseFileExtensionlessExample/" data-linktype="external">File without an extension sample .

Istool

kullanılırken, Çıkış Derlemeleri senaryosunda belirtilen tüm çıkış MSBuild -t:pack -p:IsTool=true dosyaları klasörü yerine MSBuild -t:pack -p:IsTool=truetools klasörüne lib kopyalanır. Dosyada ayarıyla DotNetCliTool belirtilenden farklı olduğunu PackageType.csproj unutmayın.

-nuspec-file">kullanarak .nuspec paketleme

Genellikle dosyada yer alan tüm özellikleri proje dosyasına dahil etmek önerilmez ancak projenizi paketlemek için bir dosya kullanmayı .nuspec seçebilirsiniz. kullanan SDK stili olmayan bir proje için, PackageReference paket görevinin NuGet.Build.Tasks.Pack.targets yürütülene kadar içeri aktarması gerekir. Yine de bir dosyayı paketlemeden önce projeyi geri nuspec yükleyebilirsiniz. (SDK stilinde bir proje varsayılan olarak paket hedeflerini içerir.)

Proje dosyasının hedef çerçevesi ilgisizdir ve paketlemede nuspec kullanılmaz. Aşağıdaki üç MSBuild özellik, bir kullanarak paketlemeyle ilgilidir: .nuspec

1. NuspecFile: paketleme için kullanılan .nuspec dosyanın göreli veya mutlak yolu.
2. NuspecProperties: anahtar=değer çiftlerinin noktalı virgülle ayrılmış listesi. Komut satırı MSBuild ayrıştırmanın çalışma yolu nedeniyle, birden çok özellik şu şekilde belirtilmelidir: -p:NuspecProperties="key1=value1;key2=value2" .
3. NuspecBasePath: Dosyanın temel .nuspec yolu.

projenizi dotnet.exe paketlemek için kullanıyorsanız, aşağıdakine benzer bir komut kullanın:

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

projenizi MSBuild paketlemek için kullanıyorsanız, aşağıdakine benzer bir komut kullanın:

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

dotnet.exe veya msbuild kullanarak paketlemenin de nuspec varsayılan olarak projeyi geliştirmeye yol aç olduğunu unutmayın. Bu, proje dosyanıza özelliği dotnet.exe proje dosyanıza ayar ile eşdeğer olan özelliğin yanı sıra proje --no-build<NoBuild>true</NoBuild> dosyasındaki <IncludeBuildOutput>false</IncludeBuildOutput> ayarıyla da engel olabilir.

Bir dosyayı paketlemek için bir .csproj dosyası örneği:

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

Özelleştirilmiş paket oluşturmak için gelişmiş uzantı noktaları

Hedef, pack iç, hedef çerçeveye özgü derlemede çalıştıran iki uzantı noktası sağlar. Uzantı noktaları, hedef çerçeveye özgü içeriği ve derlemeleri bir pakete dahil eder:

• TargetsForTfmSpecificBuildOutput target: klasörün içindeki dosyalar veya lib kullanılarak belirtilen bir klasör için BuildOutputTargetFolder kullanın.
• TargetsForTfmSpecificContentInPackage target: dışındaki dosyalar için BuildOutputTargetFolder kullanın.

TargetsForTfmSpecificBuildOutput

Özel bir hedef yazın ve özelliğin değeri olarak $(TargetsForTfmSpecificBuildOutput) belirtin. (Varsayılan olarak lib) içine gitmek gereken tüm dosyalar için, hedef bu dosyaları ItemGroup'a yazmalı ve aşağıdaki BuildOutputTargetFolder iki meta veri değerlerini BuildOutputInPackage ayarlamalı:

• FinalOutputPath: Dosyanın mutlak yolu; sağlanmazsa, kimlik kaynak yolunu değerlendirmek için kullanılır.
• TargetPath: (İsteğe bağlı) Dosyanın içinde, ilgili kültür klasörlerinin altına gidip uydu derlemeleri gibi bir alt lib\<TargetFramework> klasöre ihtiyacı olduğunda ayarlayın. Varsayılan olarak dosyanın adı kullanılır.

Örnek:

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

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

TargetsForTfmSpecificContentInPackage

Özel bir hedef yazın ve özelliğin değeri olarak $(TargetsForTfmSpecificContentInPackage) belirtin. Pakete dahil etmek istediğiniz dosyaların hedefin bu dosyaları ItemGroup'a yazması ve aşağıdaki isteğe bağlı TfmSpecificPackageFile meta verileri ayarlaması gerekir:

• PackagePath: Dosyanın pakette çıkışının gerektiği yol. NuGet aynı paket yoluna birden fazla dosya eklenirse bir uyarı sağlar.
• BuildAction: Dosyaya atanacak derleme eylemi, yalnızca paket yolu klasöründe ise contentFiles gereklidir. Varsayılan olarak "Yok".

Örnek:

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

hedefi geri yükleme

MSBuild -t:restore (ve nuget restoredotnet restore .NET Core projeleriyle birlikte kullanılır), proje dosyasında başvurulan paketleri aşağıdaki gibi geri yükleme:

1. Tüm projeden projeye başvurularını okuma
2. Ara klasörü ve hedef çerçeveleri bulmak için proje özelliklerini okuyun
3. MSBuildNuGet .Build.Tasks.dll'a veri Build.Tasks.dll
4. Geri yükleme çalıştırma
5. Paketleri indirme
6. Varlık dosyası, hedef ve teklif yazma

Hedef, restore PackageReference biçimini kullanan projeler için çalışır. MSBuild 16.5+ ayrıca MSBuild 16.5+packages.config desteğine sahip.

Özellikleri geri yükleme

Ek geri yükleme ayarları proje MSBuild dosyasındaki özelliklerden gelebilir. Değerler, anahtar kullanılarak komut satırına da -p: ayarlandırabilirsiniz (aşağıdaki örneklere bakın).

Örnekler

Komut satırı:

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

Project dosyası:

<PropertyGroup>
    <RestoreIgnoreFailedSource>true</RestoreIgnoreFailedSource>
</PropertyGroup>

Çıkışları geri yükleme

Restore derleme klasöründe aşağıdaki dosyaları oluşturur obj :

Tek bir komutla geri yükleme ve oluşturma MSBuild

NuGetHedefleri ve props 'ı getiren paketleri geri yükleyen olgu nedeniyle MSBuild , geri yükleme ve derleme değerlendirmeleri farklı genel özelliklerle çalıştırılır. Bu, aşağıdakilerin öngörülemeyen ve genellikle yanlış bir davranışa sahip olacağı anlamına gelir.

msbuild -t:restore,build

Bunun yerine önerilen yaklaşım şunlardır:

msbuild -t:build -restore

Aynı Logic şuna benzer diğer hedefler için de geçerlidir build .

İle PackageReference ve packages.config projelerini geri yükleme MSBuild

MSBuild16.5 + ile packages.config de desteklenir msbuild -t:restore .

msbuild -t:restore -p:RestorePackagesConfig=true

MSBuildStatik grafik değerlendirmesi ile geri yükleme

msbuild -t:restore -p:RestoreUseStaticGraphEvaluation=true

Alternatif olarak, bir dizin. Build. props içindeki özelliği ayarlayarak bunu etkinleştirebilirsiniz.

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

Statik grafik geri yükleme, geri yükleme 'nin MSBuild bölümünü, Proje okuma ve değerlendirme, ancak geri yükleme algoritmasını etkilemez! Geri yükleme algoritması tüm NuGet araçlarda aynıdır ( NuGet.exe, MSBuild.exe, dotnet.exe ve Visual Studio).

Birçok senaryoda, statik grafik geri yükleme geçerli geri yüklemeden farklı davranabilir ve belirtilen bazı Packagereferklu veya ProjectReferences eksik olabilir.

Bir kez göz önünde bulundurmanız için, statik grafik geri yüklemeye geçiş yaparken şunu çalıştırmayı göz önünde bulundurun:

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

NuGet hiçbir NuGet . Bir tutarsızlık görürseniz lütfen bir sorun bildirin NuGet/Home .

Bir geri yükleme grafiğinden bir kitaplığı değiştirme

Geri yükleme yanlış derlemeyi alıyorsa, bu paketlerin varsayılan seçeneğini hariç tutabilir ve kendi seçimiyle değiştirin. Birincisi, en üst düzeyle PackageReference , tüm varlıkları hariç tut:

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

Ardından, DLL 'nin uygun yerel kopyasına kendi başvurunuz ekleyin:

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