Başvuru derlemeleri

  • Makale

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ındaki 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.

Bir 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, yanlışlıkla önceki sürümde bulunmayan API üyelerini kullanabilirsiniz. Bu hatayı yalnızca programı hedef makinede 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 API kümesini 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.dll sözleşme derlemesini sağlar. Bu API'lerin uygulamaları, .NET Framework'te 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 derlemelere başvurmak için başvurular ekleyebilirsiniz. Kullanılabilir olduğunda başvuru derlemelerini kullanmanız önerilir. Bunun yapılması, yalnızca API tasarımcıları tarafından kullanılması amaçlanacak hedef sürümde desteklenen API üyelerini kullanmanızı sağlar. 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 birlikte dağıtılır. Bunları tek başına yükleyici indirerek veya Visual Studio yükleyicisinde 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 (NuGet aracılığıyla) otomatik olarak indirilir 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'ın önceki sürümleri için kullanılır).

Başvuru ekle iletişim kutusunu kullanarak Visual Studio'daki .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 proje öğesini kullanarak doğrudan MSBuild projesine 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 kullanarak -reference (C# ve Visual Basic'te) 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\ içinde bulunur. NETFramework dizini. .NET Core için, proje özelliğini trueolarak ayarlayarak PreserveCompilationContext çıkış dizininizin publish/refs alt dizinine hedef platformunuzun başvuru derlemelerini kopyalamak için yayımlama işlemini zorlayabilirsiniz. Ardından bu başvuru derleme dosyalarını derleyiciye geçirebilirsiniz. DependencyContext Microsoft.Extensions.DependencyModel paketinin kullanılması, yollarının bulunmasına yardımcı olabilir.

Uygulama içermediğinden, başvuru derlemeleri yürütme için yüklenemez. Bunu yapmak için bir System.BadImageFormatExceptionsonuç elde etmek gerekir. Bir başvuru derlemesinin içeriğini incelemek istiyorsanız, bunu .NET Framework'teki (yöntemini kullanarak Assembly.ReflectionOnlyLoad ) veya .NET ve .NET Framework'teki yalnızca yansıma bağlamı içine MetadataLoadContext yükleyebilirsiniz.

Başvuru derlemeleri oluşturma

Kitaplıklarınız için başvuru derlemeleri oluşturmak, kitaplık tüketicilerinizin programlarını kitaplığın birçok farklı sürümüne göre 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 söz konusu olduğunda derleme sürelerini azaltmak için başvuru derlemelerinden de yararlanabilir. Genellikle, artımlı derleme senaryolarında bir proje, bağlı olduğu derlemeler de dahil olmak üzere herhangi bir giriş dosyası değiştirildiğinde 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 derlemesinin uygulama derlemesi yerine giriş dosyası olarak kullanılması, 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 genişletilmesidir. 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övdeleri kullanmanın throw null nedeni (gövdelerin aksine) PEVerify'ın çalıştırılıp geçirebilmesidir (böylece meta verilerin eksiksizliğini doğrulayabilir).

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

  • Başvuru derlemesi yalnızca API yüzeyinde ihtiyaç duyduğu özelliklere 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 bunlar 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 belirlenirse 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ı, başvuru derlemeleri oluşturmak için kendi mekanizmalarını kullandıklarından bazı ayrıntılarda farklılık gösterebilir. Örneğin, vücut yerine tamamen boş metot gövdeleri throw null 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.