project.json ve UWP

2025-02-05

Önemli

Bu içerik kullanım dışı bırakıldı. Projeler PackageReference biçimlerini kullanmalıdır. project.json projenizi PackageReference 'e geçirmeyiöğrenin.

Bu belgede NuGet 3+ (Visual Studio 2015 ve üzeri) özellikleri kullanan paket yapısı açıklanmaktadır. .nuspec minClientVersion özelliği, 3.1 olarak ayarlayarak burada açıklanan özelliklere ihtiyacınız olduğunu belirtmek için kullanılabilir.

Mevcut pakete UWP desteği ekleme

Mevcut bir paketiniz varsa ve UWP uygulamaları için destek eklemek istiyorsanız, burada açıklanan paketleme biçimini benimsemeniz gerekmez. Bu biçimi yalnızca tanımladığı özelliklere ihtiyacınız varsa ve yalnızca NuGet istemcisinin 3+ sürümüne güncelleştirilmiş istemcilerle çalışmak istiyorsanız benimsemeniz gerekir.

Netcore45'i zaten hedefliyorum

netcore45 zaten hedeflediyseniz ve buradaki özelliklerden yararlanmanız gerekmiyorsa herhangi bir işlem yapmanız gerekmez. netcore45 paketleri UWP uygulamaları tarafından kullanılabilir.

Windows 10'a özgü API'lerden yararlanmak istiyorum

Bu durumda paketinize uap10.0 hedef çerçeve takma adını (TFM veya TxM) eklemeniz gerekir. Paketinizde yeni bir klasör oluşturun ve Windows 10 ile çalışmak üzere derlenmiş derlemeyi bu klasöre ekleyin.

Windows 10'a özgü API'lere ihtiyacım yok, ancak yeni .NET özellikleri istiyorum veya netcore45'im yok

Bu durumda dotnet TxM'yi paketinize eklersiniz. Diğer TxM'lerin aksine dotnet bir yüzey alanı veya platform anlamına gelmez. Paketinizin bağımlılıklarınızın üzerinde çalıştığı herhangi bir platformda çalıştığını belirtir. dotnet TxM ile bir paket oluştururken, bağlı olduğunuz BCL paketlerini tanımlamanız gerektiğinden .nuspecTxM'ye özgü bağımlılıklarınız olabilir; örneğin, System.Text, System.Xmlvb. Bu bağımlılıkların üzerinde çalıştığı konumlar, paketinizin nerede çalıştığını tanımlar.

Bağımlılıklarımı nasıl öğrenebilirim?

Hangi bağımlılıkları listeleyebileceğinizi anlamanın iki yolu vardır:

NuSpec Bağımlılık Oluşturucuüçüncü taraf aracını kullanın. Araç işlemi otomatikleştirir ve .nuspec dosyanızı derlemedeki bağımlı paketlerle güncelleştirir. NuGet paketi, NuSpec.ReferenceGeneratoraracılığıyla kullanılabilir.
(Zor yöntem) Çalışma zamanında gerçekten hangi derlemelere ihtiyaç duyulduğunu görmek için .dll'e bakmak amacıyla ILDasm kullanın. Ardından her birinin hangi NuGet paketinden geldiğini belirleyin.

dotnet TxM'yi destekleyen bir paketin oluşturulmasına yardımcı olan özellikler hakkında ayrıntılı bilgi için project.json konusuna bakın.

Önemli

Paketinizin PCL projeleriyle çalışması amaçlanıyorsa, uyarılardan ve olası uyumluluk sorunlarından kaçınmak için bir dotnet klasörü oluşturmanızı kesinlikle öneririz.

Dizin yapısı

Bu biçimi kullanan NuGet paketleri aşağıdaki iyi bilinen klasör ve davranışlara sahiptir:

Klasör	Davranış
İnşa Etmek	Bu klasördeki MSBuild hedefleri ve props dosyaları projeye farklı bir şekilde entegre edilir, ancak bunun dışında bir değişiklik yoktur.
Araçları	`install.ps1` ve `uninstall.ps1` çalıştırılmaz. `init.ps1` her zaman olduğu gibi çalışır.
İçerik	İçerik kullanıcının projesine otomatik olarak kopyalanmaz. Projeye içerik ekleme desteğinin daha sonraki bir sürümde yapılması planlanıyor.
Lib	Çoğu paket için `lib` NuGet 2.x'te olduğu gibi çalışır, ancak içinde hangi adların kullanılabileceğini gösteren genişletilmiş seçenekler ve paketleri kullanırken doğru alt klasörü seçmek için daha iyi bir mantık sunar. Ancak, `ref`ile birlikte kullanıldığında `lib` klasörü, `ref` klasöründeki derlemeler tarafından tanımlanan yüzey alanını uygulayan derlemeler içerir.
Ref	`ref`, bir uygulamanın derlenecek genel yüzeyini (genel türler ve yöntemler) tanımlayan .NET derlemelerini içeren isteğe bağlı bir klasördür. Bu klasördeki derlemelerin uygulaması olmayabilir, bunlar yalnızca derleyici için yüzey alanını tanımlamak için kullanılır. Paketin `ref` klasörü yoksa, `lib` hem başvuru derlemesi hem de uygulama derlemesi olur.
Çalıştırma Zamanları	`runtimes`, CPU mimarisi ve işletim sistemine özgü veya platforma bağlı ikili dosyalar gibi işletim sistemine özgü kod içeren isteğe bağlı bir klasördür.

Paketlerdeki MSBuild hedef ve özellik dosyaları

NuGet paketleri, paketin yüklü olduğu herhangi bir MSBuild projesine aktarılan .targets ve .props dosyaları içerebilir. NuGet 2.x'te bu, .csproj dosyasına <Import> deyimleri eklenerek gerçekleştirilir; NuGet 3.0'da belirli bir "projeye yükleme" eylemi yoktur. Bunun yerine paket geri yükleme işlemi [projectname].nuget.props ve [projectname].NuGet.targetsiki dosya yazar.

MSBuild bu iki dosyayı aramasını bilir ve bunları proje derleme işleminin başına ve sonuna yakın bir şekilde otomatik olarak içeri aktarır. Bu, NuGet 2.x'e çok benzer bir davranış sağlar, ancak önemli bir fark vardır: bu durumda hedef/props dosyalarının sıralaması garanti edilmez. Ancak MSBuild, <Target> tanımının BeforeTargets ve AfterTargets öznitelikleri aracılığıyla hedefleri sıralamanın yollarını sağlar (bkz. Hedef Öğesi (MSBuild).

Lib ve Referans

NuGet v3'te lib klasörünün davranışı önemli ölçüde değişmemiştir. Ancak, tüm derlemeler bir TxM'den sonra adlandırılan alt klasörler içinde olmalıdır ve artık doğrudan lib klasörüne yerleştirilemiyor. TxM, bir paketteki belirli bir varlığın çalışması gereken platformun adıdır. Mantıksal olarak bunlar Hedef Çerçeve Monikerlarının (TFM) bir uzantısıdır; örneğin, net45, net46, netcore50ve dnxcore50, TxM'lerin tüm örnekleridir (bkz. Hedef Çerçeveler). TxM, bir çerçeveye (TFM) ve platforma özgü diğer yüzey alanlarına başvurabilir. Örneğin UWP TxM (uap10.0), .NET yüzey alanını ve UWP uygulamaları için Windows yüzey alanını temsil eder.

Örnek bir lib yapısı:

lib
├───net40
│       MyLibrary.dll
└───wp81
        MyLibrary.dll

lib klasörü çalışma zamanında kullanılan derlemeleri içerir. Çoğu paket için hedef TxM'lerin her biri için lib altındaki bir klasör gereklidir.

Ref

Bazen derleme sırasında farklı bir derleme kullanılması gereken durumlar vardır (.NET Başvuru Derlemeleri bunu bugün yapar). Bu gibi durumlarda, "ref" adı verilen, "Başvuru Derlemeleri"ni işaret eden bir üst düzey klasör kullanın.

Çoğu paket yazarı ref klasörünü gerektirmez. Derleme ve IntelliSense için tutarlı bir yüzey alanı sağlaması gereken ancak farklı TxM'ler için farklı uygulamaları olan paketler için kullanışlıdır. Bunun en büyük kullanım örneği, NuGet üzerinde .NET Core gönderiminin bir parçası olarak üretilen System.* paketleridir. Bu paketler, tutarlı bir referans derlemeleri kümesi ile birleştirilen çeşitli uygulamalara sahiptir.

Mekanik olarak, ref klasörüne dahil edilen derlemeler, derleyiciye geçirilen başvuru derlemeleridir. csc.exe kullananlar için bunlar C# /reference seçeneğine geçiş yaptığımız derlemelerdir.

ref klasörünün yapısı libile aynıdır, örneğin:

└───MyImageProcessingLib
        ├───lib
        │   ├───net40
        │   │       MyImageProcessingLibrary.dll
        │   │
        │   ├───net451
        │   │       MyImageProcessingLibrary.dll
        │   │
        │   └───win81
        │           MyImageProcessingLibrary.dll
        │
        └───ref
            ├───net40
            │       MyImageProcessingLibrary.dll
            │
            └───portable-net451-win81
                    MyImageProcessingLibrary.dll

Bu örnekte, ref dizinlerindeki derlemelerin tümü aynı olacaktır.

Çalışma Zamanları

Çalışma zamanları klasörü, genellikle İşletim Sistemi ve CPU mimarisi tarafından tanımlanan belirli "çalışma zamanlarında" çalışmak için gereken derlemeleri ve yerel kitaplıkları içerir. Bu çalışma zamanları, win, win-x86, win7-x86, win8-64vb. Çalışma Zamanı Tanımlayıcıları (RID) kullanılarak tanımlanır.

Platforma özgü API'leri kullanmak için yerel yardımcılar

Aşağıdaki örnekte, birkaç platform için tamamen yönetilen bir uygulamaya sahip olan ancak Windows 8'e özgü yerel API'leri çağırabildiği Windows 8'de yerel yardımcıları kullanan bir paket gösterilmektedir.

└───MyLibrary
        ├───lib
        │   └───net40
        │           MyLibrary.dll
        │
        └───runtimes
            ├───win8-x64
            │   ├───lib
            │   │   └───net40
            │   │           MyLibrary.dll
            │   │
            │   └───native
            │           MyNativeLibrary.dll
            │
            └───win8-x86
                ├───lib
                │   └───net40
                │           MyLibrary.dll
                │
                └───native
                        MyNativeLibrary.dll

Yukarıdaki pakete göre aşağıdaki işlemler gerçekleşir:

Windows 8'de olmadığında lib/net40/MyLibrary.dll derlemesi kullanılır.
Windows 8'de runtimes/win8-<architecture>/lib/MyLibrary.dll kullanılır ve native/MyNativeHelper.dll derlemenizin çıkışına kopyalanır.

Yukarıdaki örnekte lib/net40 derlemesi tamamen yönetilen koddur, ancak çalışma zamanları klasöründeki derlemeler Windows 8'e özgü API'leri çağırmak için yerel yardımcı derlemeye p/invoke yapacaktır.

Yalnızca tek bir lib klasörü seçilebilir, bu nedenle çalışma zamanına özgü bir klasör varsa, çalışma zamanına özgü olmayan libüzerinden seçilir. Yerel klasör ekleyici bir klasördür; eğer mevcutsa, yapının çıktısına kopyalanır.

Yönetilen sarmalayıcı

Çalışma zamanlarını kullanmanın başka bir yolu, yalnızca yönetilen bir sarmalayıcı olan bir paketi, yerli bir yazılım bileşeni üzerinde taşımaktır. Bu senaryoda aşağıdaki gibi bir paket oluşturursunuz:

└───MyLibrary
        └───runtimes
            ├───win8-x64
            │   ├───lib
            │   │   └───net451
            │   │           MyLibrary.dll
            │   │
            │   └───native
            │           MyImplementation.dll
            │
            └───win8-x86
                ├───lib
                │   └───net451
                │           MyLibrary.dll
                │
                └───native
                        MyImplementation.dll

Bu durumda, ilgili yerel derlemeye bağlı olmayan bu paketin hiçbir uygulaması olmadığından, bu klasör gibi en üst düzey lib klasörü yoktur. MyLibrary.dllyönetilen derleme bu iki durumda da tam olarak aynıysa, bunu en üst düzey lib klasörüne koyabiliriz, ancak yerel derlemenin olmaması, win-x86 veya win-x64 olmayan bir platforma yüklenmişse paketin yüklenememesine neden olmadığından üst düzey lib kullanılır ancak yerel derleme kopyalanamaz.

NuGet 2 ve NuGet 3 için paket yazma

hem packages.config hem de project.json kullanan paketler kullanılarak projeler tarafından kullanılabilecek bir paket oluşturmak istiyorsanız, aşağıdakiler geçerlidir:

Başvuru (Ref) ve çalışma zamanları yalnızca NuGet 3'te çalışır. Her ikisi de NuGet 2 tarafından yoksayılır.
çalışması için install.ps1 veya uninstall.ps1 güvenemezsiniz. Bu dosyalar packages.configkullanılırken yürütülür, ancak project.jsonile göz ardı edilir. Bu nedenle, paketinizi çalıştırmadan kullanabilmeniz gerekir. init.ps1 hala NuGet 3 üzerinde çalışır.
Hedefler ve Props yüklemesi farklıdır, bu nedenle paketinizin her iki istemcide de beklendiği gibi çalıştığından emin olun.
Lib'in alt dizinleri NuGet 3'te bir TxM olmalıdır. Kitaplıkları lib klasörünün köküne yerleştiremezsiniz.
NuGet 3 ile içerik otomatik olarak kopyalanmaz. Paketinizin tüketicileri dosyaları kendileri kopyalayabilir veya dosyaları otomatikleştirmek için görev çalıştırıcısı gibi bir araç kullanabilir.
Kaynak ve yapılandırma dosyası dönüştürmeleri NuGet 3 tarafından çalıştırılmaz.

NuGet 2 ve 3'i destekliyorsanız, minClientVersion paketinizin üzerinde çalıştığı en düşük NuGet 2 istemcisi sürümü olmalıdır. Mevcut bir paket söz konusu olduğunda, bu paketin değiştirilmesi gerekmez.

Aracılığıyla paylaş