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:

Etiket Açıklama Varsayılan Değer
IncludeAssets Bu varlıklar kullanılacak tümü
ExcludeAssets Bu varlıklar tüketilmeyecek yok
PrivateAssets Bu varlıklar kullanılacak ancak üst projeye akmayacak contentfiles; Analizörleri; Oluşturmak

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:

Value Açıklama
derle lib Klasörün içeriği ve projenizin klasör içindeki derlemelere göre derlenip derlenemediğini denetler
çalışma zamanı ve runtimes klasörünün lib içeriği ve bu derlemelerin derleme çıktı dizinine kopyalanıp kopyalanmayacağını denetler
contentFiles contentfiles Klasörün içeriği
derleme .propsbuild ve .targets klasöründe
buildMultitargeting (4.0).props ve .targetsbuildMultitargeting klasöründe, çerçeveler arası hedefleme için
buildTransitive (5,0+).propsbuildTransitive ve .targets klasöründe, tüketen herhangi bir projeye geçişli olarak akan varlıklar için. Özellik sayfasına bakın.
Analizörleri .NET çözümleyicileri
yerel native Klasörün içeriği
yok Yukarıdakilerin hiçbiri kullanılmaz.
tümü Yukarıdakilerin tümü (hariç none)
<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.

Not

developmentDependency Bir .nuspec dosyada olarak true ayarlandığında, bu işlem paketi yalnızca geliştirme bağımlılığı olarak işaretler ve bu da paketin diğer paketlere bağımlılık olarak eklenmesini önler. PackageReference (NuGet 4.8+) ile bu bayrak, derleme zamanı varlıklarını derlemenin dışında tutacağı anlamına da gelir. Daha fazla bilgi için bkz . PackageReference için DevelopmentDependency desteği.

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:

The result of applying a Condition on PackageReference with VS2017

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.

Not

Bir projenin packages.lock.json kök dizininde dosyası olduğunda, özellik RestorePackagesWithLockFile ayarlanmasa bile kilit dosyası her zaman geri yükleme ile birlikte kullanılır. Bu nedenle bu özelliği kabul etmenin bir diğer yolu da projenin kök dizininde sahte boş packages.lock.json bir dosya oluşturmaktır.

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 lockedmodetruebunu 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 PackageX2.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.0PackageX 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.exe seçeneği dotnet seçeneği MSBuild eşdeğeri seçeneği Açıklama
-UseLockFile --use-lock-file RestorePackagesWithLockFile Kilit dosyasının kullanımını kabul eder.
-LockedMode --locked-mode RestoreLockedMode Geri yükleme için kilitli modu etkinleştirir. Bu, yinelenebilir derlemeler istediğiniz CI/CD senaryolarında kullanışlıdır.
-ForceEvaluate --force-evaluate RestoreForceEvaluate Bu seçenek, projede tanımlanan kayan sürüme sahip paketlerde kullanışlıdır. Varsayılan olarak, bu seçenekle geri yüklemeyi çalıştırmadığınız sürece NuGet geri yükleme her geri yüklemede paket sürümünü otomatik olarak güncelleştirmez.
-LockFilePath --lock-file-path NuGetLockFilePath Proje için özel bir kilit dosyası konumu tanımlar. NuGet varsayılan olarak kök dizinde destekler packages.lock.json . Aynı dizinde birden çok projeniz varsa NuGet projeye özgü kilit dosyasını destekler packages.<project_name>.lock.json

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.

Proje çerçevesi AssetTargetFallback Paket çerçeveleri Sonuç
.NET Framework 4.7.2 .NET Standard 2.0 .NET Standard 2.0
.NET Core Uygulaması 3.1 .NET Standard 2.0, .NET Framework 4.7.2 .NET Standard 2.0
.NET Core Uygulaması 3.1 .NET Framework 4.7.2 Uyumsuz, ile başarısız NU1202
.NET Core Uygulaması 3.1 net472; net471 .NET Framework 4.7.2 .NET Framework 4.7.2 ile NU1701

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.

Not

.NET SDK tabanlı bir proje kullanıyorsanız, uygun $(AssetTargetFallback) değerler yapılandırılır ve bunları el ile ayarlamanız gerekmez.

$(PackageTargetFallback) bu sınamayı ele alma girişiminde bulunan daha önceki bir özellikti, ancak temel olarak bozuktur ve kullanılmamalıdır . uygulamasından $(PackageTargetFallback) öğesine geçiş yapmak için $(AssetTargetFallback)özellik adını değiştirmeniz yeterlidir.