System.Runtime.Versioning.ComponentGuaranteesAttribute sınıfı

  • Makale

Bu makale, bu API'nin başvuru belgelerine ek açıklamalar sağlar.

ComponentGuaranteesAttribute, bileşen ve sınıf kitaplıklarının geliştiricileri tarafından, kitaplıklarının tüketicilerinin birden çok sürümde bekleyebileceği uyumluluk düzeyini belirtmek için kullanılır. Kitaplığın veya bileşenin gelecekteki bir sürümünün var olan bir istemciyi bozmayacağı garanti düzeyini gösterir. İstemciler daha sonra sürümleri arasında kararlılığı sağlamak için kendi arabirimlerini tasarlamada yardımcı olarak kullanabilir ComponentGuaranteesAttribute .

Not

Ortak dil çalışma zamanı (CLR) bu özniteliği hiçbir şekilde kullanmaz. Değeri, bileşen yazarının amacını resmi olarak belgelemede yatmaktadır. Derleme zamanı araçları, aksi takdirde bildirilen garantiyi bozacak derleme zamanı hatalarını algılamak için bu bildirimleri de kullanabilir.

Uyumluluk düzeyleri

, ComponentGuaranteesAttribute sabit listesi üyeleri ComponentGuaranteesOptions tarafından temsil edilen aşağıdaki uyumluluk düzeylerini destekler:

  • Sürümden sürüme uyumluluk (ComponentGuaranteesOptions.None). İstemci, gelecekteki sürümlerin mevcut istemciyi bozacağını bekleyebilir. Daha fazla bilgi için bu makalenin devamında Yer alan Uyumluluk yok bölümüne bakın.

  • Yan yana sürümden sürüme uyumluluk (ComponentGuaranteesOptions.SideBySide). Aynı uygulama etki alanına derlemenin birden fazla sürümü yüklendiğinde bileşen çalışacak şekilde test edilmiştir. Genel olarak, gelecekteki sürümler uyumluluğu bozabilir. Ancak, hataya neden olan değişiklikler yapıldığında, eski sürüm değiştirilmez, ancak yeni sürümle birlikte bulunur. Hataya neden olan değişiklikler yapıldığında mevcut istemcilerin çalışmasını sağlamak için beklenen yol yan yana yürütmedir. Daha fazla bilgi için bu makalenin devamındaki Yan yana uyumluluk bölümüne bakın.

  • Kararlı sürümden sürüme uyumluluk (ComponentGuaranteesOptions.Stable). Gelecekteki sürümler istemciyi kesmemeli ve yan yana yürütmeye gerek olmamalıdır. Ancak, istemci yanlışlıkla bozulursa, sorunu çözmek için yan yana yürütme kullanmak mümkün olabilir. Daha fazla bilgi için Kararlı uyumluluk bölümüne bakın.

  • Exchange sürümden sürüme uyumluluk (ComponentGuaranteesOptions.Exchange). Gelecekteki sürümlerin istemciyi bozmamasını sağlamak için olağanüstü özen gösterilir. İstemci, yalnızca birbirinden bağımsız olarak dağıtılan diğer derlemelerle iletişim için kullanılan arabirimlerin imzasında bu türleri kullanmalıdır. Bu türlerin yalnızca bir sürümünün belirli bir uygulama etki alanında olması beklenir; başka bir deyişle, istemci bozulursa, yan yana yürütme uyumluluk sorununu çözemez. Daha fazla bilgi için Exchange türü uyumluluğu bölümüne bakın.

Aşağıdaki bölümlerde her bir garanti düzeyi daha ayrıntılı olarak açıklanmıştır.

Uyumluluk yok

Bir bileşeni olarak ComponentGuaranteesOptions.None işaretlemek, sağlayıcının uyumluluk konusunda hiçbir garanti sağlamadığını gösterir. İstemciler, kullanıma sunulan arabirimlere bağımlılık almaktan kaçınmalıdır. Bu uyumluluk düzeyi, deneysel olan veya genel kullanıma sunulan ancak yalnızca her zaman aynı anda güncelleştirilen bileşenlere yönelik türler için kullanışlıdır. None bu bileşenin dış bileşenler tarafından kullanılmaması gerektiğini açıkça belirtir.

Yan yana uyumluluk

Bir bileşeni olarak ComponentGuaranteesOptions.SideBySide işaretlemek, aynı uygulama etki alanına birden fazla derleme sürümü yüklendiğinde bileşenin çalışmak üzere test edildiğini gösterir. Hataya neden olan değişiklikler, daha büyük sürüm numarasına sahip derlemede yapıldığı sürece izin verilir. Derlemenin eski bir sürümüne bağlı olan bileşenlerin eski sürüme bağlanmaya devam etmesi beklenir ve diğer bileşenler yeni sürüme bağlanabilir. Eski sürümü yıkıcı bir şekilde değiştirerek olduğu bildirilen SideBySide bir bileşeni güncelleştirmek de mümkündür.

Kararlı uyumluluk

Bir türü olarak ComponentGuaranteesOptions.Stable işaretlemek, türün sürümler arasında kararlı kalması gerektiğini gösterir. Ancak, aynı uygulama etki alanında kararlı bir türün yan yana sürümlerinin mevcut olması da mümkün olabilir.

Kararlı türler yüksek ikili uyumluluk çubuğu tutar. Bu nedenle sağlayıcılar kararlı türlerde hataya neden olan değişiklikler yapmaktan kaçınmalıdır. Aşağıdaki değişiklik türleri kabul edilebilir:

  • Serileştirme biçimini bozmadığı sürece bir türe özel örnek alanları ekleme veya alan kaldırma.
  • Serileştirilebilir olmayan bir türü serileştirilebilir bir türe değiştirme. (Ancak, serileştirilebilir bir tür serileştirilebilir olmayan bir türe değiştirilemez.)
  • Bir yöntemden yeni, daha türetilmiş özel durumlar oluşturma.
  • Bir yöntemin performansını geliştirme.
  • Değişiklik, istemcilerin çoğunluğunu olumsuz etkilemediği sürece dönüş değerleri aralığının değiştirilmesi.
  • İş gerekçesi yüksekse ve olumsuz etkilenen istemcilerin sayısı düşükse ciddi hataları düzeltin.

Kararlı bileşenlerin yeni sürümlerinin mevcut istemcileri bozması beklenmediği için, genellikle bir uygulama etki alanında kararlı bir bileşenin yalnızca bir sürümü gerekir. Ancak, kararlı türler tüm bileşenlerin üzerinde anlaşmaya vardığı iyi bilinen değişim türleri olarak kullanılmadığından bu bir gereksinim değildir. Bu nedenle, kararlı bir bileşenin yeni bir sürümü yanlışlıkla bazı bileşenleri bozarsa ve diğer bileşenler yeni sürüme ihtiyaç duyarsa, hem eski hem de yeni bileşeni yükleyerek sorunu çözmek mümkün olabilir.

Stable sürümünden daha güçlü bir sürüm uyumluluğu garantisi Nonesağlar. Bu, çok sürümlü bileşenler için yaygın bir varsayılandır.

Stable ile SideBySidebirleştirilebilir. Bu, bileşenin uyumluluğu bozmayacağını ancak belirli bir uygulama etki alanına birden fazla sürüm yüklendiğinde çalışacak şekilde test edilebileceğini belirtir.

Bir tür veya yöntem olarak Stableişaretlendikten sonra sürümüne Exchangeyükseltilebilir. Ancak, bu sürüme Nonedüşürülemez.

Exchange türü uyumluluğu

Bir türü olarak ComponentGuaranteesOptions.Exchange işaretlemek, sürümünden daha Stablegüçlü bir sürüm uyumluluğu garantisi sağlar ve tüm türlerin en kararlısına uygulanmalıdır. Bu türlerin, bağımsız olarak oluşturulmuş bileşenler arasında her iki zamandaki tüm bileşen sınırları (CLR'nin herhangi bir sürümü veya bir bileşen veya uygulamanın herhangi bir sürümü) ve boşluk (çapraz işlem, tek işlemde çapraz CLR, tek bir CLR'de çapraz uygulama etki alanı) değişim için kullanılması amaçlanmıştır. Exchange türünde hataya neden olan bir değişiklik yapılırsa, türün birden çok sürümünü yükleyerek sorunu çözmek mümkün değildir.

Exchange türleri yalnızca bir sorun çok ciddi olduğunda (ciddi bir güvenlik sorunu gibi) veya kırılma olasılığı çok düşük olduğunda (yani davranış, kodun akla gelebilecek bir bağımlılık almadığı rastgele bir şekilde kırılmışsa) değiştirilmelidir. Bir değişim türünde aşağıdaki türlerde değişiklik yapabilirsiniz:

  • Yeni arabirim tanımlarının devralınımını ekleyin.

  • Yeni devralınan arabirim tanımlarının yöntemlerini uygulayan yeni özel yöntemler ekleyin.

  • Yeni statik alanlar ekleyin.

  • Yeni statik yöntemler ekleyin.

  • Yeni sanal olmayan örnek yöntemleri ekleyin.

Aşağıdakiler hataya neden olan değişiklikler olarak kabul edilir ve ilkel türler için izin verilmez:

  • Serileştirme biçimleri değiştiriliyor. Sürüme dayanıklı serileştirme gereklidir.

  • Özel örnek alanları ekleme veya kaldırma. Bu, türün serileştirme biçimini değiştirme ve yansıma kullanan hataya neden olan istemci kodunu değiştirme riski taşır.

  • Bir türün seri hale getirilebilirliğini değiştirme. Seri hale getirilemeyen bir tür seri hale getirilemez veya tam tersi olabilir.

  • Bir yöntemden farklı özel durumlar oluşturma.

  • Üye tanımı bu olasılığı artırmadığı ve istemcilerin bilinmeyen değerleri nasıl işleyeceklerini açıkça belirtmediği sürece yöntemin dönüş değerlerinin aralığını değiştirme.

  • Hataların çoğunu düzelttik. Türün tüketicileri mevcut davranışa güvenir.

Bir bileşen, tür veya üye garantiyle Exchange işaretlendikten sonra veya Noneolarak Stable değiştirilemez.

Genellikle, exchange türleri ortak arabirimlerde yaygın olarak kullanılan temel türler (.Int32NET'te ve String gibi) ve arabirimlerdir (, , ve IComparable<T>gibiIList<T>IEnumerable<T>).

Exchange türleri yalnızca uyumlulukla Exchange işaretlenmiş diğer türleri genel kullanıma sunabilir. Ayrıca, değişim türleri değişmeye eğilimli Windows API'lerinin davranışına bağlı olamaz.

Bileşen garantileri

Aşağıdaki tablo, bir bileşenin özelliklerinin ve kullanımının uyumluluk garantisini nasıl etkilediğini gösterir.

Bileşen özellikleri Exchange Dengeli Yan Yana Hiçbiri
Bağımsız olarak sürüm oluşturan bileşenler arasındaki arabirimlerde kullanılabilir. Y N N N
Bağımsız olarak sürüm oluşturan bir derleme tarafından (özel olarak) kullanılabilir. Y Y Y N
Tek bir uygulama etki alanında birden çok sürüm olabilir. N Y Y Y
Hataya neden olan değişiklikler yapabilir N N Y Y
Derlemenin belirli birden çok sürümünün birlikte yüklenmesini sağlamak için test edilmiştir. N N Y N
Hataya neden olan değişiklikler yapabilir. N N N Y
Çok güvenli, kırılmayan bakım değişiklikleri yapabilir. Y Y Y Y

Özniteliğini uygulama

öğesini ComponentGuaranteesAttribute bir derlemeye, türe veya tür üyesine uygulayabilirsiniz. Uygulaması hiyerarşiktir. Yani, varsayılan olarak, derleme düzeyinde özniteliğinin özelliği tarafından Guarantees tanımlanan garanti, derlemedeki tüm türlerin ve bu türlerdeki tüm üyelerin garantisini tanımlar. Benzer şekilde, garanti türüne uygulanırsa, varsayılan olarak türün her üyesi için de geçerlidir.

Devralınan bu garanti, tek tek türler ve tür üyelerine uygulanarak ComponentGuaranteesAttribute geçersiz kılınabilir. Ancak, varsayılanı geçersiz kılmanın yalnızca garantiyi zayıflatabileceğini garanti eder; Onu güçlendiremezler. Örneğin, bir derleme garantiyle None işaretlenmişse, türleri ve üyeleri uyumluluk garantisi yoktur ve derlemedeki türlere veya üyelere uygulanan diğer garantiler yoksayılır.

Garantiyi test edin

Guarantees özelliği, özniteliğiyle işaretlenmiş numaralandırmanın ComponentGuaranteesOptions bir üyesini FlagsAttribute döndürür. Başka bir deyişle, bilinmeyen olası bayrakları maskeleyerek ilgilendiğiniz bayrağı test etmelisiniz. Örneğin, aşağıdaki örnek bir türün olarak Stableişaretlenip işaretlenmediğini sınar.

// Test whether guarantee is Stable.
if ((guarantee & ComponentGuaranteesOptions.Stable) == ComponentGuaranteesOptions.Stable)
   Console.WriteLine("{0} is marked as {1}.", typ.Name, guarantee);

' Test whether guarantee is Stable.
If (guarantee And ComponentGuaranteesOptions.Stable) = ComponentGuaranteesOptions.Stable Then
   Console.WriteLine("{0} is marked as {1}.", typ.Name, guarantee)
End If

Aşağıdaki örnek, bir türün veya Exchangeolarak Stable işaretlenip işaretlenmediğini sınar.

// Test whether guarantee is Stable or Exchange.
if ((guarantee & (ComponentGuaranteesOptions.Stable | ComponentGuaranteesOptions.Exchange)) > 0)
   Console.WriteLine("{0} is marked as Stable or Exchange.", typ.Name, guarantee);

' Test whether guarantee is Stable or Exchange.
If (guarantee And (ComponentGuaranteesOptions.Stable Or ComponentGuaranteesOptions.Exchange)) > 0 Then
   Console.WriteLine("{0} is marked as Stable or Exchange.", typ.Name, guarantee)
End If

Aşağıdaki örnek, bir türün (ne ne de StableExchange) olarak None işaretlendiğini sınar.

// Test whether there is no guarantee (neither Stable nor Exchange).
if ((guarantee & (ComponentGuaranteesOptions.Stable | ComponentGuaranteesOptions.Exchange)) == 0)
   Console.WriteLine("{0} has no compatibility guarantee.", typ.Name, guarantee);

' Test whether there is no guarantee (neither Stable nor Exchange).
If (guarantee And (ComponentGuaranteesOptions.Stable Or ComponentGuaranteesOptions.Exchange)) = 0 Then
   Console.WriteLine("{0} has no compatibility guarantee.", typ.Name, guarantee)
End If