Aracılığıyla paylaş

Referans 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ı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. Eğer doğrudan uygulama derlemesine derlerseniz, önceki sürümde mevcut olmayan API üyelerini yanlışlıkla 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.dllsö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.

Referans derlemelerini kullanma

Projenizdeki belirli API'leri kullanmak için onların derlemelerine başvuru noktaları eklemeniz gerekir. Uygulama derlemelerine veya başvuru derlemelerine referanslar ekleyebilirsiniz. Kullanılabilir olduğunda başvuru derlemelerini kullanmanız her zaman tavsiye edilir. 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\.NETFramework dizininde yer alır. .NET Core için, proje özelliğini olarak ayarlayarak PreserveCompilationContext çıkış dizininizin true 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 yapmaya çalışmak bir System.BadImageFormatException ile sonuçlanır. Bir başvuru derlemesinin içeriğini incelemek istiyorsanız, bunu .NET Framework'teki yalnızca yansıma bağlamına ( Assembly.ReflectionOnlyLoad yöntemini kullanarak) veya .NET ve .NET Framework'te MetadataLoadContext içine 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ı ne zaman değiştirirse, derleme değişir. Referans derlemesi yalnızca genel API üzerinde değişiklik yapıldığında 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.

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

Referans derlemeler, yalnızca meta veri içeren derlemeler 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. throw null gövdelerini kullanmanın nedeni (gövdelerin olmadığı duruma kıyasla), PEVerify'in çalıştırılıp geçmesine imkan tanımaktır; böylece meta verilerin eksiksizliği doğrulanabilir.

Başvuru derlemeleri, yalnızca meta veri derlemelerindeki özel üyeler gibi meta verileri 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 referansları olabilir. Örneğin, class C { private void M() { dynamic d = 1; ... } } için başvuru derlemesi, dynamic için gerekli olan türlerden hiçbirine başvurmaz.
  • Özel fonksiyon üyeleri (yöntemler, özellikler ve olaylar), kaldırılmalarının derlemeyi gözle görülür ş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 tutmayı sürdürür:

  • Ö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, özellikler ve olaylar açık bir şekilde uygulanır.
  • 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.

Uyarı

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, throw null gövdesi yerine 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 bakınız

  • Last updated on