Başvuru derlemeleri

Başvuru derlemeleri , kitaplığın genel API yüzeyini temsil etmek için gereken en düşük meta veri miktarını içeren özel bir derleme türüdür. Derleme araçlarında bir derlemeye başvururken önemli olan tüm üyeler için bildirimler içerir, ancak API sözleşmeleri üzerinde gözlemlenebilir bir etkisi olmayan özel üyelerin tüm üye uygulamalarını ve bildirimlerini dışlarlar. Buna karşılık, normal derlemeler uygulama derlemeleri olarak adlandırılır.

Başvuru derlemeleri yürütme için yüklenemez, ancak uygulama derlemeleriyle aynı şekilde derleyici girişi olarak geçirilebilir. Başvuru derlemeleri genellikle belirli bir platform veya kitaplığın Yazılım Geliştirme Seti (SDK) ile dağıtılır.

Başvuru derlemesi kullanmak, geliştiricilerin bu sürüm için tam uygulama derlemesine sahip olmadan belirli bir kitaplık sürümünü hedefleyen programlar oluşturmasına olanak tanır. Makinenizde yalnızca bir kitaplığın en son sürümüne sahip olduğunuzu, ancak bu kitaplığın önceki bir sürümünü hedefleyen bir program oluşturmak istediğinizi varsayalım. Doğrudan uygulama derlemesine karşı derlerseniz, önceki sürümde bulunmayan API üyelerini istemeden kullanabilirsiniz. Bu hatayı yalnızca hedef makinede programı test ederken bulursunuz. Önceki sürüm için başvuru derlemesine karşı derleme yaparsanız, hemen bir derleme zamanı hatası alırsınız.

Başvuru derlemesi, bir sözleşmeyi, yani somut uygulama derlemesine karşılık olmayan bir DIZI API'yi de temsil edebilir. Sözleşme derlemesi olarak adlandırılan bu tür başvuru derlemeleri, aynı API kümesini destekleyen birden çok platformu hedeflemek için kullanılabilir. Örneğin. .NET Standard, farklı .NET platformları arasında paylaşılan ortak API'ler kümesini temsil eden netstandard.dllsözleşme derlemesini sağlar. Bu API'lerin uygulamaları, .NET Framework üzerinde mscorlib.dll veya .NET Core'da System.Private.CoreLib.dll gibi farklı platformlardaki farklı derlemelerde yer alır. .NET Standard'ı hedefleyen bir kitaplık.NET Standard'ı destekleyen tüm platformlarda çalıştırılabilir.

Başvuru derlemelerini kullanma

Projenizdeki belirli API'leri kullanmak için derlemelerine başvuru eklemeniz gerekir. Uygulama derlemelerine veya başvuru derlemelerine başvuru ekleyebilirsiniz. Kullanılabilir olduğunda başvuru derlemelerini kullanmanız önerilir. Bunun yapılması, yalnızca API tasarımcıları tarafından kullanılmak üzere hedef sürümde desteklenen API üyelerini kullandığınızdan emin olur. Başvuru derlemesini kullanmak, uygulama ayrıntılarına bağımlılık almamanızı sağlar.

.NET Framework kitaplıkları için başvuru derlemeleri, hedefleme paketleriyle dağıtılır. Bunları tek başına bir yükleyici indirerek veya Visual Studio yükleyicide bir bileşen seçerek elde edebilirsiniz. Daha fazla bilgi için bkz. Geliştiriciler için .NET Framework yükleme. .NET Core ve .NET Standard için başvuru derlemeleri gerektiğinde otomatik olarak indirilir (NuGet aracılığıyla) ve başvurulur. .NET Core 3.0 ve üzeri için, çekirdek çerçeve için başvuru derlemeleri Microsoft.NETCore.App.Ref paketindedir ( Microsoft.NETCore.App paketi 3.0 öncesi sürümler için kullanılır).

başvuru ekle iletişim kutusunu kullanarak Visual Studio .NET Framework derlemelerine başvuru eklediğinizde, listeden bir derleme seçersiniz ve Visual Studio projenizde seçilen hedef çerçeve sürümüne karşılık gelen başvuru derlemelerini otomatik olarak bulur. Aynı durum, Başvuru projesi öğesini kullanarak doğrudan MSBuild projeye başvuru eklemek için de geçerlidir: Tam dosya yolunu değil, yalnızca derleme adını belirtmeniz gerekir. Komut satırında derleyici seçeneğini (-referenceC# ve Visual Basic içinde) veya Roslyn API'sindeki yöntemini kullanarak Compilation.AddReferences bu derlemelere başvuru eklediğinizde, doğru hedef platform sürümü için başvuru derleme dosyalarını el ile belirtmeniz gerekir. .NET Framework başvuru derleme dosyaları %ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\ konumunda bulunur. NETFramework dizini. .NET Core için, proje özelliğini trueolarak ayarlayarakPreserveCompilationContext, hedef platformunuzun başvuru derlemelerini çıkış dizininizin publish/refs alt dizinine kopyalamak için yayımlama işlemini zorlayabilirsiniz. Ardından bu başvuru derleme dosyalarını derleyiciye geçirebilirsiniz. Microsoft.Extensions.DependencyModel paketinin kullanılmasıDependencyContext, yollarının bulunmasına yardımcı olabilir.

Uygulama içermediğinden, başvuru derlemeleri yürütme için yüklenemez. Bunu yapmaya çalışmak sonucunda bir System.BadImageFormatExceptionolur. Başvuru derlemesinin içeriğini incelemek istiyorsanız, bunu .NET Framework 'de (yöntemini kullanarakAssembly.ReflectionOnlyLoad) veya .NET Core'da yalnızca yansıma bağlamı içine MetadataLoadContext yükleyebilirsiniz.

Başvuru derlemeleri oluşturma

Kitaplıklarınızın başvuru derlemelerini oluşturmak, kitaplık tüketicilerinizin programlarını kitaplığın birçok farklı sürümünde oluşturması gerektiğinde yararlı olabilir. Uygulama derlemelerinin tüm bu sürümler için dağıtılması, büyük boyutları nedeniyle pratik olmayabilir. Başvuru derlemelerinin boyutu daha küçüktür ve bunları kitaplığınızın SDK'sının bir parçası olarak dağıtmak indirme boyutunu küçültür ve disk alanından tasarruf sağlar.

IDE'ler ve derleme araçları, birden çok sınıf kitaplığından oluşan büyük çözümler olması durumunda derleme sürelerini azaltmak için başvuru derlemelerinden de yararlanabilir. Genellikle artımlı derleme senaryolarında, bağımlı olduğu derlemeler de dahil olmak üzere giriş dosyalarından herhangi biri değiştirildiğinde proje yeniden oluşturulur. Programcı herhangi bir üyenin uygulamasını her değiştirerek uygulama derlemesi değişir. Başvuru derlemesi yalnızca genel API etkilendiğinde değişir. Bu nedenle, başvuru derlemesini uygulama derlemesi yerine giriş dosyası olarak kullanmak, bazı durumlarda bağımlı projenin derlemesinin atlanmasına olanak tanır.

Başvuru derlemeleri oluşturabilirsiniz:

Başvuru derlemelerini NuGet paketleriyle dağıtmak istiyorsanız, bunları uygulama derlemeleri için kullanılan lib\ alt dizini yerine paket dizininin altındaki ref\ alt dizinine eklemeniz gerekir.

Başvuru derlemeleri yapısı

Başvuru derlemeleri, yalnızca meta veri derlemeleri olan ilgili kavramın bir genişlemesidir. Yalnızca meta veri derlemelerinin yöntem gövdeleri tek throw null bir gövdeyle değiştirilir, ancak anonim türler dışındaki tüm üyeleri içerir. Gövdelerin (gövdelerin aksine) kullanılmasının throw null nedeni , PEVerify'ın çalıştırılıp geçirebilmesidir (böylece meta verilerin eksiksizliğini doğrular).

Başvuru derlemeleri yalnızca meta veri derlemelerinden meta verileri (özel üyeler) daha fazla kaldırır:

  • Başvuru derlemesi yalnızca API yüzeyinde ihtiyaç duyduğu şeye yönelik başvurulara sahiptir. Gerçek derlemenin belirli uygulamalarla ilgili ek başvuruları olabilir. Örneğin, için class C { private void M() { dynamic d = 1; ... } } başvuru derlemesi için gereken hiçbir türe dynamicbaşvurmaz.
  • Özel işlev üyeleri (yöntemler, özellikler ve olaylar), kaldırmalarının derlemeyi gözlenemeyecek şekilde etkilemediği durumlarda kaldırılır. InternalsVisibleTo özniteliği yoksa, iç işlev üyeleri de kaldırılır.

Başvuru derlemelerindeki meta veriler aşağıdaki bilgileri tutmaya devam eder:

  • Özel ve iç içe türler de dahil olmak üzere tüm türler.
  • Tüm öznitelikler, hatta iç öznitelikler.
  • Tüm sanal yöntemler.
  • Açık arabirim uygulamaları.
  • Erişimcileri sanal olduğundan açıkça uygulanan özellikler ve olaylar.
  • Tüm yapı alanları.

Başvuru derlemeleri, derleme düzeyinde bir ReferenceAssembly özniteliği içerir. Bu öznitelik kaynakta belirtilebilir; derleyicinin bunu sentezleye gerek yoktur. Bu öznitelik nedeniyle çalışma zamanları yürütme için başvuru derlemelerini yüklemeyi reddeder (ancak yalnızca yansıma modunda yüklenebilir).

Tam başvuru derleme yapısı ayrıntıları derleyici sürümüne bağlıdır. Daha yeni sürümler, genel API yüzeyini etkilemediği belirlendiyse daha fazla meta verileri dışlama seçeneğini belirleyebilir.

Not

Bu bölümdeki bilgiler yalnızca C# sürüm 7.1 veya Visual Basic sürüm 15.3'ten başlayarak Roslyn derleyicileri tarafından oluşturulan başvuru derlemeleri için geçerlidir. .NET Framework ve .NET Core kitaplıkları için başvuru derlemelerinin yapısı, kendi başvuru derlemeleri oluşturma mekanizmalarını kullandıklarından bazı ayrıntılarda farklılık gösterebilir. Örneğin, vücut yerine throw null tamamen boş metot gövdeleri olabilir. Ancak genel ilke hala geçerlidir: kullanılabilir yöntem uygulamaları yoktur ve yalnızca genel API perspektifinden gözlemlenebilir bir etkiye sahip üyeler için meta veriler içerirler.

Ayrıca bkz.