PackageReference proje dosyalarında

MSBuild öğelerini kullanarak <PackageReference> paket başvuruları, ayrı packages.config bir dosyaya sahip olmanın aksine nuget paket bağımlılıklarını doğrudan proje dosyaları içinde belirtir. PackageReference kullanımı NuGet'in diğer yönlerini etkilemez; örneğin, dosyalardaki NuGet.Config ayarlar (paket kaynakları dahil) Yaygın NuGet yapılandırmalarında açıklandığı gibi uygulanmaya devam eder.

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

Proje türü desteği

PackageReference varsayılan olarak C++ UWP projeleri dışında Windows 10 Derleme 15063 (Creators Update) ve sonraki sürümleri hedefleyen .NET Core projeleri, .NET Standard projeleri ve UWP projeleri için kullanılır. .NET Framework projeleri PackageReference'ı destekler, ancak şu anda varsayılan değeridir packages.config. PackageReference'ı kullanmak için bağımlılıkları packages.config proje dosyanıza geçirin ve packages.config dosyasını kaldırın.

Tam .NET Framework'leri hedefleyen ASP.NET uygulamalar PackageReference için yalnızca sınırlı destek içerir. C++ ve JavaScript proje türleri desteklenmez.

PackageReference Ekleme

Aşağıdaki söz dizimini 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ırkenkiyle packages.configaynıdır:

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

Yukarıdaki örnekte, 3.6.0, Paket sürümü oluşturma konusunda açıklandığı gibi en düşük sürümü tercih eden >=3.6.0 olan herhangi bir sürüm anlamına gelir.

Paket bağımlılığı olmayan bir proje için PackageReference kullanma

Gelişmiş: Projede yüklü paket yoksa (proje dosyasında PackageReference yoksa ve packages.config dosyası yoksa) ancak projenin PackageReference stili olarak geri yüklenmesini istiyorsanız, proje dosyanızda RestoreProjectStyle Proje özelliğini PackageReference olarak ayarlayabilirsiniz.

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

PackageReference stilindeki projelere (mevcut csproj veya SDK stili projeler) başvurursanız, bu yararlı olabilir. Bu, bu projelerin başvurduğunu paketlerin projeniz tarafından "geçişli" olarak başvurulmasını sağlar.

PackageReference ve kaynaklar

PackageReference projelerinde geçişli bağımlılık sürümleri geri yükleme zamanı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 PackageReferencedesteklenir:

<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

Bir bağımlılığı yalnızca geliştirme koşumu olarak kullanıyor olabilirsiniz ve bunu paketinizi kullanacak projelere göstermek istemeyebilirsiniz. Bu senaryoda, bu davranışı denetlemek için meta verileri kullanabilirsiniz PrivateAssets .

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

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

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

Aşağıdaki meta veri etiketleri bağımlılık varlıklarını denetler:

Bu etiketler için izin verilen değerler aşağıda gösterildiği gibi, ile dışında noktalı virgülle all ayrılmış ve none kendi başlarına görünmesi gereken birden çok değer vardır:

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

ile birlikte PrivateAssetsolmadığından, hedeflerin build ve prop'ların üst projeye akacağını unutmayın. Örneğin, yukarıdaki başvurunun AppLogger adlı bir NuGet paketi oluşturan bir projede kullanıldığını düşünün. AppLogger, AppLogger kullanan projeler gibi hedeflerini Contoso.Utility.UsefulStuffve prop'larını da kullanabilir.

PackageReference koşulu ekleme

Bir paketin dahil edilip edilmediğini denetlemek için bir koşul kullanabilirsiniz; burada koşullar herhangi bir MSBuild değişkenini veya hedefler veya props dosyasında tanımlanan bir değişkeni kullanabilir. Ancak şu anda yalnızca TargetFramework değişkeni desteklenmektedir.

Örneğin, hem hedeflediğiniz netstandard1.4 hem net452 de yalnızca için net452geçerli olan bir bağımlılığınız olduğunu varsayalım. Bu durumda, paketinizi kullanan bir netstandard1.4 projenin bu gereksiz bağımlılığı eklemesini istemezsiniz. Bunu önlemek için, üzerinde PackageReference aşağıdaki gibi bir koşul belirtirsiniz:

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

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

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

<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 ve Visual Studio 2019 16.0 veya üzeri sürümlerde kullanılabilir.

Bazen bir MSBuild hedefinden bir paketteki dosyalara başvurmak istenir. Tabanlı projelerde packages.config paketler proje dosyasına göre bir klasöre yüklenir. Ancak PackageReference'ta paketler, makineden makineye farklılık gösterebilen genel paketler klasöründen tüketilir.

Bu boşluğu kapatmak için NuGet, paketin tüketileceği konuma işaret eden bir özellik sundu.

Ö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, araçlar klasörü içeren paketler için otomatik olarak özellikler oluşturur.

  <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 olmadığından, paket kimliğinin sözcüğüyle Pkgönekli bir MSBuild kolay adıyla değiştirilmesi gerekir. Oluşturulan özelliğin tam adını doğrulamak için oluşturulan nuget.g.props dosyasına bakın.

PackageReference Diğer Adları

Bazı nadir durumlarda farklı paketler aynı ad alanında sınıflar içerir. ProjectReference'a eşdeğer NuGet 5.7 ve Visual Studio 2019 Güncelleştirme 7'den başlayarak PackageReference destekler Aliases. Varsayılan olarak hiçbir diğer ad sağlanmadı. Bir diğer ad belirtildiğinde, açıklamalı paketten gelen tüm derlemelere bir diğer adla başvuru yapılması gerekir.

NuGet\Samples konumunda ö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>

ve kodda 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}");
        }
...
}

NuGet uyarıları ve hataları

Bu özellik NuGet 4.3 veya üzeri ve Visual Studio 2017 15.3 veya üzeri sürümlerde kullanılabilir.

Birçok paket ve geri yükleme senaryosu için tüm NuGet uyarıları ve hataları kodlanıp ile NU****başlayın. Tüm NuGet uyarıları ve hataları başvuru belgelerinde listelenir.

NuGet aşağıdaki uyarı özelliklerini gözlemler:

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

Ö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

Paketiniz ve geri yükleme işlemleriniz sırasında tüm NuGet uyarılarını çözmeniz önerilir ancak bazı durumlarda bunları gizlemeniz gerekir. Bir uyarı projesini geniş çapta engellemek için şunları yapmayı göz önünde bulundurun:

<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ıyı daha seçmeli olarak NoWarn gizlemeyi seçebiliriz.

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

Visual Studio'da NuGet paketi uyarılarını gizleme

Visual Studio'dayken uyarıları IDE aracılığıyla da gizleyebilirsiniz .

Bağımlılıkları kilitleme

Bu özellik NuGet 4.9 veya üzeri ve Visual Studio 2017 15.9 veya üzeri sürümlerde kullanılabilir.

NuGet geri yüklemesine giriş, proje dosyasından PackageReference bir dizi öğedir (üst düzey veya doğrudan bağımlılıklar) ve çıkış, geçişli bağımlılıklar da dahil olmak üzere tüm paket bağımlılıklarının tam olarak kapatılmasıdır. Giriş PackageReference listesi değişmediyse NuGet her zaman paket bağımlılıklarının tam kapanışını oluşturmaya çalışır. Ancak, bunu yapamadığı bazı senaryolar vardır. Örneğin:

• gibi <PackageReference Include="My.Sample.Lib" Version="4.*"/>kayan sürümleri kullandığınızda. Burada amaç paketlerin her geri yüklemesinde en son sürüme geçmek olsa da, kullanıcıların açık bir hareketle grafiğin belirli bir en son sürüme kilitlenmesini ve varsa daha sonraki bir sürüme kaydırılması gerektiğini gerektiren senaryolar vardır.

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

  • 1. Gün: Belirttiyseniz <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'dı. Bu durumda NuGet 4.1.0 (en yakın en düşük sürüm) olarak çözümlenebilirdi

  • 2. Gün: Sürüm 4.0.0 yayımlanır. NuGet artık tam eşleşmeyi bulacak ve 4.0.0 ile çözümlemeye başlayacak

• Belirli bir paket sürümü depodan kaldırılır. nuget.org paket silme işlemlerine izin vermese de, tüm paket depolarında bu kısıtlama yoktur. Bu, Silinen sürüme çözümlenemediğinde NuGet'in en iyi eşleşmeyi bulmasına neden olur.

Kilit dosyasını etkinleştirme

Paket bağımlılıklarının tam olarak kapatılmasını kalıcı hale getirmek için projeniz için MSBuild özelliğini ayarlayarak kilit dosyası özelliğini RestorePackagesWithLockFile kabul edebilirsiniz:

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

Bu özellik ayarlanırsa NuGet geri yükleme, proje kök dizininde tüm paket bağımlılıklarını listeleyen bir kilit dosyası - packages.lock.json dosyası oluşturur.

restore kilit dosyasıyla davranış

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

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

CI/CD ve paket bağımlılıklarını anında değiştirmek istemediğiniz diğer senaryolarda, öğesini olarak ayarlayarak lockedmode truebunu yapabilirsiniz:

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 da ayarlayabilirsiniz:

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

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

Kilit dosyasını kaynak deponuzun parçası yapma

Bir uygulama oluşturuyorsanız, yürütülebilir dosya ve söz konusu proje bağımlılık zincirinin başındadır, ardından NuGet'in geri yükleme sırasında kullanabilmesi için kilit dosyasını kaynak kod deposuna iade edin.

Ancak, projeniz göndermediğiniz bir kitaplık projesi veya diğer projelerin bağımlı olduğu ortak bir kod projesiyse, kaynak kodunuzun bir parçası olarak kilit dosyasını iade etmemelisiniz . Kilit dosyasını tutmanın bir zararı yoktur, ancak bu ortak kod projesine bağımlı olan bir projenin geri yüklenmesi/derlenmesi sırasında kilit dosyasında listelendiği gibi ortak kod projesi için kilitli paket bağımlılıkları kullanılamayabilir.

Örn.

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

Bir sürüme PackageX 2.0.0 bağımlılığı varsa ve ayrıca sürümüne 1.0.0bağlı PackageX başvurular ProjectB varsaProjectA, için ProjectB kilit dosyası sürümüne 1.0.0bağımlılığı PackageX listeler. Ancak, ProjectA oluşturulduğunda, kilit dosyası sürümüne 2.0.0 PackageX bağımlılık içerir ve için ProjectBkilit dosyasında listelenmez1.0.0. Bu nedenle, ortak bir kod projesinin kilit dosyası, buna bağlı projeler için çözümlenen paketler üzerinde çok az söz sahibidir.

Dosya genişletilebilirliğini kilitle

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

NuGet Bağımlılık Çözümleyicisi

NuGet bağımlılık çözümleyicisi, bağımlılık çözümleme belgesinde açıklandığı gibi 4 kuralı izler.

Geri yükleme işleminin performansını ve ölçeklenebilirliğini geliştirmek için, geri yükleme algoritması 6.12 sürümünde yeniden yazıldı. 6.12 sürümünden itibaren, yeni geri yükleme algoritması tüm PackageReference projeleri için varsayılan olarak etkinleştirilir. Yeni geri yükleme algoritması, herhangi bir yazılımda olduğu gibi işlevsel olarak öncekine eşdeğer olsa da, hatalar mümkündür. Önceki uygulamaya dönmek için MSBuild özelliğini RestoreUseLegacyDependencyResolver olarak trueayarlayın.

Önceki sürümlerde yeniden üretılmamış olan 6.12, .NET 9 veya 17.12 sürümlerinde geri yükleme hatalarıyla karşılaşırsanız lütfen GitHub'da bir sorun oluşturun. Eski ve yeni algoritmalar arasındaki farklar, derleme sırasında veya çalışma zamanında olduğu gibi farklı etkilere sahip olabilir. Değişikliklerin hatalara değil, farklı paket sürümlerinin geri yüklenmesine neden olma olasılığı da vardır. Tüm değişikliklerden etkilenmiş olabileceğinizi düşünüyorsanız, NuGet geri yükleme algoritmasındaki değişikliklerin kök neden olup olmadığını doğrulamak için uygulayabileceğiniz adımlar aşağıdadır.

Geri yükleme, sonuçlarını dizine MSBuildProjectExtensionsPath yazar. Bu, farkları bulmak için yeni ve eski algoritmalarla karşılaştırılabilir. Bu genellikle derlemenizin klasörüdür obj . Sonraki adımlar için veya dotnet.exe kullanabilirsinizmsbuild.exe.

1. obj Projenizin klasörünü kaldırın.
2. msbuild -t:restore komutunu çalıştırın
3. öğesinin obj içeriğini, davranışın bu new olduğunu belirten bir konuma kaydedin.
4. msbuild -t:restore -p:RestoreUseLegacyDependencyResolver="true" komutunu çalıştırın
5. öğesinin obj içeriğini, davranışın bu legacy olduğunu belirten bir konuma kaydedin.
6. özellikle project.assets.json olmak üzere iki dizindeki dosyaları karşılaştırın. Farkları vurgulayan araçlar özellikle bunun için yararlıdır (örneğin, Visual Studio Code, her iki dosyayı da açın ve sağ tıklama "karşılaştırmak için seç" ve "seçiliyle karşılaştır" seçeneğini kullanın)

Yukarıdaki yöntemi izlerseniz, dosyalar arasında project.assets.json tam olarak 1 fark olmalıdır:

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

Başka farklar varsa lütfen GitHub'da tüm ayrıntıları içeren bir sorun oluşturun.

AssetTargetFallback

özelliği, AssetTargetFallback projenizin başvurduğunu projeler ve projenizin tükettiği NuGet paketleri için ek uyumlu çerçeve sürümleri belirtmenize olanak tanır.

kullanarak PackageReference bir paket bağımlılığı belirtirseniz ancak bu paket projelerinizin hedef çerçevesiyle uyumlu varlıklar içermiyorsa özellik AssetTargetFallback devreye girer. Başvuruda bulunılan paketin uyumluluğu, içinde AssetTargetFallbackbelirtilen her hedef çerçeve kullanılarak yeniden denetlendi. aracılığıyla bir project veya öğesine package başvurulduğunda AssetTargetFallbackNU1701 uyarısı oluşturulur.

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

Sınırlayıcı olarak kullanılarak ; birden çok çerçeve belirtilebilir. Geri dönüş çerçevesi eklemek için aşağıdakileri yapabilirsiniz:

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

Varolan AssetTargetFallback değerlere eklemek yerine üzerine yazmak isterseniz, bu seçeneği devre dışı $(AssetTargetFallback) bırakabilirsiniz.