PackageReference proje dosyalarında

paket başvuruları, düğümü kullanarak PackageReference doğrudan proje dosyaları içinde (ayrı bir dosyanın aksine) NuGet bağımlılıklarını doğrudan yönetir packages.config . çağrıldığından, NuGet diğer yönlerini etkilemediğinden, packagereference kullanma, örneğin, NuGet.Config dosyalardaki (paket kaynakları dahil) ayarlar hala NuGet.Configaçıklandığı gibi uygulanır.

packagereference ile, hedef çerçeve başına paket başvurularını veya diğer gruplandırmaları seçmek için MSBuild koşulları da kullanabilirsiniz. Ayrıca bağımlılıklar ve içerik akışı üzerinde ayrıntılı denetim sağlar. ( MSBuild hedef olarak paket ve geri yükleme NuGetdaha fazla ayrıntı için bkz.)

Project türü desteği

varsayılan olarak, packagereference, .net Core projeleri, .NET Standard projeleri ve daha sonra Windows 10 derleme 15063 (Creators Update) ve daha sonraki bir sürümü hedefleyen uwp projeleri için kullanılır ve C++ UWP projeleri hariç olur. .NET Framework projeler, packagereference destekler, ancak şu anda varsayılan olarak packages.config . PackageReference kullanmak için, bağımlılıkları proje dosyanıza geçirin ve ardından packages.config kaldırın.

tam .NET Framework hedefleyen ASP.NET uygulamalar, packagereference için yalnızca sınırlı desteği içerir. C++ ve JavaScript proje türleri desteklenmez.

PackageReference ekleme

Aşağıdaki sözdizimini kullanarak proje dosyanıza bir bağımlılık ekleyin:

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

Bağımlılık sürümünü denetleme

Bir paketin sürümünü belirtme kuralı, kullanırken olduğu gibi aynıdır packages.config :

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

Yukarıdaki örnekte, 3.6.0, >>bölümünde açıklandığı gibi en düşük sürüm için tercih içeren = 3.6.0 olan herhangi bir sürüm anlamına gelir.

Packagereferde olmayan bir proje için PackageReference kullanma

gelişmiş: bir projede yüklü paketleriniz yoksa (proje dosyasında ve packages.config dosyası yoksa), ancak projenin packagereference stili olarak geri yüklenmesini istiyorsanız, bir restoreprojectstyle Project özelliğini proje dosyanızda packagereference olarak ayarlayabilirsiniz.

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

Bu, PackageReference stilli (mevcut csproj veya SDK stili projeler) projelere başvuru yaparsanız yararlı olabilir. Bu, bu projelerin başvurduğu paketleri projeniz tarafından "geçişli" olacak şekilde sağlayacak şekilde etkinleştirir.

PackageReference ve kaynakları

PackageReference projelerinde, geçişli bağımlılık sürümleri geri yükleme sırasında çözümlenir. Bu nedenle, PackageReference projelerinde tüm kaynakların tüm geri yüklemeler için kullanılabilir olması gerekir.

Kayan sürümler

Kayan sürümler ile desteklenir :

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

Bağımlılık varlıklarını denetleme

Yalnızca bir geliştirme bandı olarak bir bağımlılık kullanıyor olabilirsiniz ve bunu paketinizi kullanacak projelere göstermek istemeyebilirsiniz. Bu senaryoda, PrivateAssets Bu davranışı denetlemek için meta verileri kullanabilirsiniz.

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

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

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

Aşağıdaki meta veri etiketleri denetim bağımlılığı varlıkları:

Bu etiketler için izin verilen değerler aşağıdaki gibidir: ile, ve arasında bir noktalı virgülle ayrılmış birden çok değer all ve none kendileri tarafından görünmesi gerekir:

Aşağıdaki örnekte, paketteki içerik dosyaları hariç her şey proje tarafından, içerik dosyaları ve çözümleyiciler hariç her şey üst projeye akacaktır.

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

    <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
        <IncludeAssets>all</IncludeAssets>
        <ExcludeAssets>contentFiles</ExcludeAssets>
        <PrivateAssets>contentFiles;analyzers</PrivateAssets>
    </PackageReference>

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

buildİle birlikte dahil edilmediğinden PrivateAssets , hedefler ve props ana projeye akacağından build emin olmanız gerekir. örneğin, yukarıdaki başvurunun appgünlükçü adlı bir NuGet paketi oluşturan bir projede kullanıldığını göz önünde bulundurun. Appgünlükçü, Contoso.Utility.UsefulStuff Appgünlükçü kullanan projeler gibi, öğesinden hedefleri ve props 'ı kullanabilir.

PackageReference koşulu ekleme

bir paketin dahil edilip edilmeyeceğini denetlemek için bir koşul kullanabilirsiniz. burada koşullar, koşulların herhangi bir MSBuild değişkenini veya hedefler ya da props dosyasında tanımlanan bir değişkeni kullanabilir. Ancak şu anda yalnızca TargetFramework değişken desteklenir.

Örneğin, hedeflentiğinizi ve netstandard1.4net452 yalnızca için geçerli olan bir bağımlılığa sahip olduğunuzu varsayalım net452 . Bu durumda, netstandard1.4 paketinize tüketen bir projenin bu gereksiz bağımlılığı eklemesini istemezsiniz. Bunu engellemek için aşağıdaki şekilde bir koşul belirtirsiniz PackageReference :

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

Bu proje kullanılarak oluşturulan bir paket, Newtonsoft. json ' ın yalnızca bir hedef için bağımlılık olarak ekleneceğini gösterir net452 :

Koşullar da ItemGroup düzeyde uygulanabilir ve tüm alt öğeler için geçerli olacaktır PackageReference :

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

GeneratePathProperty

bu özellik NuGet 5,0 veya üzeri ile ve Visual Studio 2019 16,0 ya da üzeri sürümlerde kullanılabilir.

bazen bir MSBuild hedefinden bir paketteki dosyalara başvurulmasına tercih edilir. packages.configTabanlı projelerde, paketler proje dosyası ile ilişkili bir klasöre yüklenir. Ancak, PackageReference içinde paketler, makineden makineye değişebilen küresel paketlerklasöründen kullanılır.

bu boşluğu bağlamak için, NuGet paketin tükettiği konuma işaret eden bir özellik sunmuştur.

Örnek:

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

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

ayrıca NuGet, bir araçlar klasörü içeren paketler için otomatik olarak özellikler oluşturacaktır.

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

MSBuild özellikleri ve paket kimlikleri aynı kısıtlamalara sahip değildir, bu nedenle paket kimliğinin, sözcüğün ön eki olan MSBuild kolay bir ada değiştirilmesi gerekir Pkg . Oluşturulan özelliğin tam adını doğrulamak için, oluşturulan NuGet. g. props dosyasına bakın.

PackageReference diğer adları

Nadir bazı örneklerde farklı paketler aynı ad alanındaki sınıfları içerecektir. NuGet 5,7 & Visual Studio 2019 güncelleştirme 7 ' den başlayarak, projectreference ile eşdeğer, packagereference desteklenir Aliases . Varsayılan olarak, diğer ad sağlanmaz. Bir diğer ad belirtildiğinde, ek açıklamalı paketten gelen Tüm derlemeler bir diğer adla başvurulmalıdır.

NuGet \samples adresinde örnek kullanıma bakabilirsiniz

Proje dosyasında, diğer adları aşağıdaki gibi belirtin:

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

kodda, bunu aşağıdaki gibi kullanın:

extern alias ExampleAlias;

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

uyarı ve hata NuGet

bu özellik NuGet 4,3 veya üzeri ile ve Visual Studio 2017 15,3 ya da üzeri sürümlerde kullanılabilir.

birçok paket ve geri yükleme senaryosunda, tüm NuGet uyarıları ve hataları kodlanır ve ile başlar NU**** . tüm NuGet uyarıları ve hataları başvuru belgelerinde listelenmiştir.

NuGet gözlemi aşağıdaki uyarı özelliklerini sunar:

• TreatWarningsAsErrors, tüm uyarıları hata olarak değerlendir
• WarningsAsErrors, belirli uyarıları hata olarak değerlendir
• NoWarn, proje genelinde veya paket genelinde belirli uyarıları gizleyin.

Örnekler:

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

NuGet uyarılarını gizleme

paket ve geri yükleme işlemleri sırasında tüm NuGet uyarılarını çözmeniz önerilir, ancak bazı durumlarda bunların garanti edilir. Bir uyarı projesini genelinde gizlemek için şunları yapmayı düşünün:

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

Bazen uyarılar yalnızca grafikteki belirli bir paket için geçerlidir. PackageReference öğesine bir ekleyerek bu uyarının daha seçmeli şekilde görüntülenmesini seçebiliriz NoWarn .

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

Visual Studio NuGet paket uyarılarını gizleme

Visual Studio ' de, ıde aracılığıyla uyarıları da gizleyebilirsiniz .

Bağımlılıkları kilitleme

bu özellik NuGet 4,9 veya üzeri ile ve Visual Studio 2017 15,9 ya da üzeri sürümlerde kullanılabilir.

NuGet geri yükleme girdisi, PackageReference proje dosyasından (en üst düzey veya doğrudan bağımlılıklar) bir dizi öğe kümesidir ve çıkış, geçişli bağımlılıklar dahil olmak üzere tüm paket bağımlılıklarının tam bir kapasitesinden oluşur. NuGet, giriş packagereference listesi değişmediğinde paket bağımlılıklarının her zaman aynı tam kapatılmasını üretmeye çalışır. Ancak, bunu yapamaması gereken bazı senaryolar vardır. Örnek:

• Gibi kayan sürümler kullandığınızda <PackageReference Include="My.Sample.Lib" Version="4.*"/> . Buradaki amaç paketlerin her geri yükleme işlemi için en son sürüme kaymalıdır, ancak kullanıcıların grafiğin belirli bir en son sürüme kilitlenmesini gerektiren senaryolar vardır ve açık bir hareket üzerine varsa, daha sonraki bir sürüme float olur.

• Bir paketin, PackageReference sürümü gereksinimleriyle eşleşen daha yeni bir sürümü yayımlandı. Örneğin

  • 1. gün: belirtilirse <PackageReference Include="My.Sample.Lib" Version="4.0.0"/> , ancak NuGet depolarında kullanılabilen sürümler 4.1.0, 4.2.0 ve 4.3.0. bu durumda, NuGet 4.1.0 (en yakın minimum sürüm) olarak çözümlenmelidir

  • 2. gün: sürüm 4.0.0 yayımlandı. NuGet artık tam eşleşmeyi bulacak ve 4.0.0 'e çözümlemeyi başlatacak

• Belirli bir paket sürümü depodan kaldırılır. Nuget.org, paket silimine izin vermediği halde tüm paket depolarında Bu kısıtlama yoktur. bunun sonucunda, silinen sürüme çözümleyemediği zaman en iyi eşleşmeyi bulma NuGet.

Kilit dosyası etkinleştiriliyor

paket bağımlılıklarının tam kapatılmasını kalıcı hale getirmek için, projeniz için MSBuild özelliğini ayarlayarak dosya kilitle özelliğini kabul edebilirsiniz RestorePackagesWithLockFile :

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

bu özellik ayarlandıysa, NuGet restore, packages.lock.json proje kök dizininde tüm paket bağımlılıklarını listeleyen bir kilit dosya dosyası oluşturacaktır.

restore kilit dosyası ile davranış

proje için bir kilit dosyası varsa, NuGet çalıştırmak için bu kilit dosyasını kullanır restore . NuGet, paket bağımlılıklarında proje dosyasında (veya bağımlı proje dosyaları) bahsedildiği gibi herhangi bir değişiklik olup olmadığını görmek için hızlı bir denetim yapar ve değişiklik olmadığında yalnızca kilit dosyasında bahsedilen paketleri geri yükler. Paket bağımlılıklarının yeniden değerlendirilmesi yoktur.

NuGet, proje dosyasında bahsedildiği gibi tanımlanan bağımlılıklarda bir değişiklik algılarsa, paket grafiğini yeniden değerlendirir ve kilit dosyasını proje için yeni paket kapanışını yansıtacak şekilde güncelleştirir.

CI/CD ve diğer senaryolar için, anında paket bağımlılıklarını değiştirmek istemediğiniz için, ' yi ' e ayarlayarak bunu yapabilirsiniz lockedmodetrue :

dotnet.exe için şunu çalıştırın:

> dotnet.exe restore --locked-mode

msbuild.exe için şunu çalıştırın:

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

bu koşullu MSBuild özelliğini proje dosyanızda de ayarlayabilirsiniz:

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

Kilitli mod ise geri yükleme işlemi, kilit true dosyası oluşturulduktan sonra, proje için tanımlanan paket bağımlılıklarını güncelleştirdikten sonra tam paketleri kilit dosyasında listelenen şekilde geri yükler ya da başarısız olur.

Kaynak deponuzun kilit dosyası parçasını oluşturma

bir uygulama oluşturuyorsanız, bir çalıştırılabilir dosya ve söz konusu proje, bağımlılık zincirinin başlangıcında yer alıyorsa, NuGet geri yükleme sırasında kullanabilmesi için kilit dosyasını kaynak kodu deposuna iade edin.

Ancak, projeniz sevk ettiğiniz bir kitaplık projem veya diğer projelerin bağımlı olduğu ortak bir kod projesi ise, kilit dosyasını kaynak kodunuzun bir parçası olarak iade etmeniz gerekir . Kilit dosyası tutulmayan bir sorun yoktur ancak ortak kod projesi için kilitli paket bağımlılıkları, bu ortak kod projesine bağlı bir projenin geri yükleme/oluşturma işlemi sırasında kilit dosyasında listelendiği gibi kullanılamaz.

Örn.

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

Bir ProjectA sürüme bağımlılığının yanı PackageX2.0.0 sıra ProjectB sürüme bağlı olan başvurular varsa PackageX1.0.0 , için kilit dosyası ProjectB sürüme bir bağımlılık listeleyecek PackageX1.0.0 . Ancak, yapılandırıldığında ProjectA kilit dosyası, PackageX2.0.0ProjectA1.0.0 için kilit dosyasında listelenenlerin değil, sürüm için bir bağımlılık içerecektir ProjectB . Bu nedenle, ortak bir kod projesinin kilit dosyası, kendisine bağımlı olan projeler için çözümlenen paketlerin üzerinde çok daha fazla bilgiye sahiptir.

Kilit dosyası genişletilebilirliği

Aşağıda açıklandığı gibi kilit dosyası ile geri yükleme davranışlarını çeşitli davranışlar için denetleyebilirsiniz:

AssetTargetFallback

özelliği, projenizin AssetTargetFallback başvurduğu projeler için ek uyumlu çerçeve sürümlerini belirtmenize olanak sağlar ve projenizin kullandığı paketlere NuGet.

Kullanarak bir paket bağımlılığı belirtirseniz PackageReference , ancak bu paket, projelerinizin hedef çerçevesiyle uyumlu olan varlıkları içermiyorsa, AssetTargetFallback özelliği yürütmeye gelir. Başvurulan paketin uyumluluğu, içinde belirtilen her bir hedef çerçeve kullanılarak yeniden denetlenir AssetTargetFallback . Bir project veya package öğesine ile başvurulduğunda AssetTargetFallback , project uyarısı başlatılır.

Uyumluluğun nasıl etkilendiğine ilişkin örnekler için aşağıdaki tabloya bakın AssetTargetFallback .

Ayırıcı olarak kullanılarak birden çok çerçeve belirtilebilir ; . Bir geri dönüş çerçevesi eklemek için aşağıdakileri yapabilirsiniz:

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

$(AssetTargetFallback)Varolan değerlere eklemek yerine üzerine yazmak isterseniz, ' ı kapatabilirsiniz AssetTargetFallback .