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

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ümler arasında kararlılığı sağlamak için kendi arabirimlerini tasarlamaya yardımcı olarak ComponentGuaranteesAttribute kullanabilir.

Uyarı

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, ComponentGuaranteesOptions numaralandırma üyeleri tarafından temsil edilen aşağıdaki uyumluluk düzeylerini destekler:

• Sürümden sürüme uyumluluk yok (ComponentGuaranteesOptions.None). İstemci, gelecekteki sürümlerin mevcut istemciyi bozacağını bekleyebilir. Daha fazla bilgi için bu makalenin ilerleyen bölümlerinde 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. Değişiklikler işlevselliği bozduğunda 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 bozmasın ve paralel yürütme gerekmemelidir. Ancak, istemci yanlışlıkla bozulursa, sorunu çözmek için eş zamanlı 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

Bileşeni ComponentGuaranteesOptions.None olarak 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

Bileşenin ComponentGuaranteesOptions.SideBySide olarak işaretlenmesi, aynı uygulama etki alanına birden fazla derleme sürümü yüklendiğinde bileşenin çalışmak üzere test edildiğini gösterir. Uyumsuz 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 SideBySide olarak bildirilen bir bileşeni güncelleştirmek de mümkündür.

Kararlı uyumluluk

Bir türün ComponentGuaranteesOptions.Stable olarak işaretlenmesi, 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 bir ikili uyumluluk standardını korur. Bu nedenle sağlayıcılar kararlı türlerde hataya yol açan değişiklikler yapmaktan kaçınmalıdır. Aşağıdaki değişiklik türleri kabul edilebilir:

• Serileştirme formatını bozmadığı sürece bir türe özel örnek alanlar eklemek veya alanları kaldırmak.
• 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.
• Dönüş değerleri aralığının değiştirilmesi, bu değişiklik çoğunluğu olumsuz etkilemediği sürece mümkündür.
• İş 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, None'dan daha güçlü bir sürüm uyumluluğu garantisi sağlar. Bu, çok sürümlü bileşenler için yaygın bir varsayılandır.

Stable, bileşenin uyumluluğu bozmayacağını belirten ve belirli bir uygulama etki alanına birden fazla sürüm yüklendiğinde çalıştığı test edilen SideBySideile birleştirilebilir.

Bir tür veya yöntem Stableolarak işaretlendikten sonra Exchangeyükseltilebilir. Ancak, Noneolarak düşürülemez.

Exchange türü uyumluluğu

Bir türü ComponentGuaranteesOptions.Exchange olarak işaretlemek, Stable'den daha güçlü bir sürüm uyumluluğu garantisi sağlar ve tüm türlerin en kararlısına uygulanmalıdır. Bağımsız olarak oluşturulmuş bileşenler arasında zaman (CLR'nin herhangi bir sürümü veya bir bileşen ya da uygulamanın herhangi bir sürümü) ve mekân (farklı süreçler arasında, tek bir süreçte farklı CLR'lar arasında, tek bir CLR'de farklı uygulama alanları arasında) boyutlarında değişim sağlamak amacıyla bu türler kullanılmak üzere tasarlanmış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 bozucu değişiklikler olarak kabul edilir ve ilkel türler için izin verilmemektedir:

• 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 riskini ve yansıma kullanan istemci kodunun bozulmasına yol açabilir.

• Bir türün seri hale getirilebilirliğini değiştirme. Serileştirilemeyen bir tür serileştirilemeyeceği gibi, serileştirilebilir bir tür de serileştirilemez.

• Bir yöntemden farklı istisnalar fırlatma.

• Ü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 Exchange garantisiyle işaretlendikten sonra, Stable veya Noneolarak değiştirilemez.

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

Exchange türleri, yalnızca Exchange uyumluluğu ile işaretlenmiş diğer türleri açık olarak erişilebilir kılabilir. 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	Değiş tokuş etmek	İstikrarlı	Yan Yana	Hiç kimse
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
Önemli 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
Yerinde bozucu değişiklikler yapabilir.	N	N	N	Y
Çok güvenli, hizmet kesintisine yol açmayan değişiklikler yapabilir.	Y	Y	Y	Y

Özniteliğini uygulama

ComponentGuaranteesAttribute bir derlemeye, türe veya tür üyesine uygulayabilirsiniz. Uygulaması hiyerarşiktir. Yani, varsayılan olarak, derleme düzeyinde özniteliğin Guarantees özelliği tarafından 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.

Bu devralınan garanti, ComponentGuaranteesAttribute'ın tek tek türler ve tür üyelerine uygulanmasıyla geçersiz kılınabilir. Ancak, varsayılanı geçersiz kılmak yalnızca garantiyi zayıflatabilir; onu güçlendiremez. Örneğin, bir derleme None garantisiyle işaretlenmişse, türleri ve üyeleri uyumluluk garantisine sahip değildir ve derlemedeki türlere veya üyelere uygulanan diğer garantiler yoksayılır.

Garantiyi test edin

Guarantees özelliği, ComponentGuaranteesOptions özniteliğiyle işaretlenmiş FlagsAttribute numaralandırmasının bir üyesini 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 Stableolarak işaretlenip işaretlenmediğini sınar.

// Test whether guarantee is Stable.
if ((guarantee & ComponentGuaranteesOptions.Stable) == ComponentGuaranteesOptions.Stable)
   Console.WriteLine($"{typ.Name} is marked as {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 Stable veya Exchangeolarak işaretlenip işaretlenmediğini sınar.

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

' 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 None olarak işaretlenip işaretlenmediğini (yani, ne Stable ne de Exchange olduğu) test eder.

// Test whether there is no guarantee (neither Stable nor Exchange).
if ((guarantee & (ComponentGuaranteesOptions.Stable | ComponentGuaranteesOptions.Exchange)) == 0)
   Console.WriteLine($"{typ.Name} has no compatibility 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