System.Runtime.Versioning.ComponentGuaranteesAttribute 클래스

아티클
01/08/2024

이 문서에서는 이 API에 대한 참조 설명서에 대한 추가 설명서를 제공합니다.

ComponentGuaranteesAttribute 구성 요소 및 클래스 라이브러리 개발자가 라이브러리 소비자가 여러 버전에서 기대할 수 있는 호환성 수준을 나타내는 데 사용됩니다. 라이브러리 또는 구성 요소의 이후 버전이 기존 클라이언트를 중단하지 않을 것이라는 보장 수준을 나타냅니다. 그런 다음 클라이언트는 버전 전반에서 ComponentGuaranteesAttribute 안정성을 보장하기 위해 자체 인터페이스를 설계하는 데 도움을 줍니다.

참고 항목

CLR(공용 언어 런타임)은 이 특성을 어떤 방식으로도 사용하지 않습니다. 해당 값은 구성 요소 작성자의 의도를 공식적으로 문서화하는 데 있습니다. 컴파일 시간 도구는 이러한 선언을 사용하여 선언된 보증을 위반하는 컴파일 시간 오류를 검색할 수도 있습니다.

호환성 수준

열 ComponentGuaranteesAttribute 거형의 멤버 ComponentGuaranteesOptions 가 나타내는 다음과 같은 호환성 수준을 지원합니다.

버전 대 버전 호환성(ComponentGuaranteesOptions.None)이 없습니다. 클라이언트는 이후 버전이 기존 클라이언트를 중단시킬 것으로 예상할 수 있습니다. 자세한 내용은 이 문서의 뒷부분에 있는 호환성 없음 섹션을 참조하세요.
병렬 버전 대 버전 호환성(ComponentGuaranteesOptions.SideBySide). 구성 요소는 동일한 애플리케이션 도메인에 어셈블리의 둘 이상의 버전이 로드 될 때 작동 하도록 테스트 되었습니다. 일반적으로 이후 버전은 호환성을 손상할 수 있습니다. 그러나 호환성이 손상되는 변경이 수행되면 이전 버전은 수정되지 않지만 새 버전과 함께 존재합니다. 병렬 실행은 호환성이 손상되는 변경이 수행될 때 기존 클라이언트가 작동하도록 하는 데 필요한 방법입니다. 자세한 내용은 이 문서의 뒷부분에 있는 병렬 호환성 섹션을 참조하세요.
안정적인 버전 대 버전 호환성(ComponentGuaranteesOptions.Stable). 이후 버전은 클라이언트를 중단해서는 안 되며 병렬 실행이 필요하지 않습니다. 그러나 클라이언트가 실수로 손상된 경우 병렬 실행을 사용하여 문제를 해결할 수 있습니다. 자세한 내용은 안정적인 호환성 섹션을 참조하세요.
Exchange 버전 간 호환성(ComponentGuaranteesOptions.Exchange). 이후 버전이 클라이언트를 중단하지 않도록 주의를 기울입니다. 클라이언트는 서로 독립적으로 배포된 다른 어셈블리와의 통신에 사용되는 인터페이스의 서명에서 이러한 형식만 사용해야 합니다. 이러한 형식 중 하나의 버전 즉, 클라이언트 중단 된 경우-병렬 실행 수 없습니다. 호환성 문제를 해결할 수정 지정된 애플리케이션 도메인에 있을 예정입니다. 자세한 내용은 Exchange 형식 호환성 섹션을 참조하세요.

다음 섹션에서는 각 보장 수준에 대해 자세히 설명합니다.

호환성 없음

구성 요소를 표시 ComponentGuaranteesOptions.None 하면 공급자가 호환성을 보장하지 않음을 나타냅니다. 클라이언트는 노출된 인터페이스에 대한 종속성을 사용하지 않아야 합니다. 이 수준의 호환성은 실험적이거나 공개적으로 노출되지만 항상 동시에 업데이트되는 구성 요소에만 적용되는 형식에 유용합니다. None 은 외부 구성 요소에서 이 구성 요소를 사용하면 안 됨을 명시적으로 나타냅니다.

병렬 호환성

구성 요소가 표시 ComponentGuaranteesOptions.SideBySide 구성 요소는 테스트 어셈블리의 버전이 둘 이상 동일한 애플리케이션 도메인에 로드 되 면 작업을 나타냅니다. 버전 번호가 더 큰 어셈블리에 대한 호환성이 손상되는 변경은 허용됩니다. 이전 버전의 어셈블리에 바인딩된 구성 요소는 이전 버전에 계속 바인딩되어야 하며 다른 구성 요소는 새 버전에 바인딩할 수 있습니다. 이전 버전을 파괴적으로 수정하여 선언된 구성 요소를 업데이트할 SideBySide 수도 있습니다.

안정적인 호환성

형식을 버전 간에 안정적으로 ComponentGuaranteesOptions.Stable 기본 형식을 다시 지정해야 했음을 나타냅니다. 그러나 동일한 애플리케이션 도메인에 존재 하는 안정적인 유형 side-by-side-버전용 수도 있습니다 것입니다.

안정적인 형식은 높은 이진 호환성 표시줄을 기본. 이 때문에 공급자는 안정적인 형식에 대한 호환성이 손상되는 변경을 방지해야 합니다. 다음과 같은 종류의 변경이 허용됩니다.

serialization 형식을 중단하지 않는 한 형식에 프라이빗 인스턴스 필드를 추가하거나 형식에서 필드를 제거합니다.
직렬화할 수 없는 형식을 직렬화할 수 있는 형식으로 변경합니다. 그러나 직렬화할 수 있는 형식은 직렬화할 수 없는 형식으로 변경할 수 없습니다.
메서드에서 파생된 새 예외를 throw합니다.
메서드의 성능 향상
변경 내용이 대부분의 클라이언트에 부정적인 영향을 주지 않는 한 반환 값의 범위를 변경합니다.
비즈니스 정당성이 높고 부정적인 영향을 받는 클라이언트 수가 낮은 경우 심각한 버그를 수정합니다.

새 버전의 안정적인 구성 요소를 기존 클라이언트를 중단 하므로 일반적으로 안정 된 구성 요소의 버전을 하나만 필요 애플리케이션 도메인에서 합니다. 그러나 안정적인 형식은 모든 구성 요소가 동의하는 잘 알려진 교환 형식으로 사용되지 않으므로 이는 요구 사항이 아닙니다. 따라서 안정적인 구성 요소의 새 버전이 실수로 일부 구성 요소를 중단하고 다른 구성 요소에 새 버전이 필요한 경우 이전 구성 요소와 새 구성 요소를 모두 로드하여 문제를 해결할 수 있습니다.

Stable 는 .보다 None더 강력한 버전 호환성 보장을 제공합니다. 다중 버전 구성 요소에 대한 일반적인 기본값입니다.

Stable 함께 사용할 수 있습니다 SideBySide, 구성 요소 호환성을 중단 하지 것입니다 하지만 둘 이상의 버전이 지정 된 애플리케이션 도메인에 로드 될 때 제대로 작동 하는지 테스트 되는 상태입니다.

형식 또는 메서드가 로 표시된 후에는 .로 Stable업그레이드 Exchange할 수 있습니다. 그러나 으로 다운그레이드 None할 수는 없습니다.

Exchange 형식 호환성

형식을 로 ComponentGuaranteesOptions.Exchange 표시하면 보다 강력한 버전 호환성 보장 Stable이 제공되며 모든 형식 중에서 가장 안정적인 버전에 적용해야 합니다. 이러한 형식은 모두 시간 (CLR의 모든 버전) 또는 구성 요소 또는 애플리케이션의 모든 버전에서에서 모든 구성 요소 경계를 넘어 독립적으로 빌드된 구성 요소와 공간 (프로세스 간, 단일 프로세스에서 크로스-CLR 간 교환에 사용할 수는 애플리케이션 간 도메인 하나 CLR에서). 교환 형식에 대한 호환성이 손상되는 변경이 발생하는 경우 여러 버전의 형식을 로드하여 문제를 해결할 수 없습니다.

교환 형식은 문제가 매우 심각하거나(예: 심각한 보안 문제) 중단 가능성이 매우 낮은 경우에만 변경해야 합니다(즉, 코드가 종속성을 가질 수 없는 임의의 방식으로 동작이 이미 중단된 경우). 다음과 같은 종류의 교환 유형을 변경할 수 있습니다.

새 인터페이스 정의의 상속을 추가합니다.
새로 상속된 인터페이스 정의의 메서드를 구현하는 새 프라이빗 메서드를 추가합니다.
새 정적 필드를 추가합니다.
새 정적 메서드를 추가합니다.
가상이 아닌 새 인스턴스 메서드를 추가합니다.

다음은 호환성이 손상되는 변경으로 간주되며 기본 형식에는 허용되지 않습니다.

serialization 형식 변경 버전에 관대한 serialization이 필요합니다.
프라이빗 인스턴스 필드 추가 또는 제거 이렇게 하면 형식의 serialization 형식이 변경되고 리플렉션을 사용하는 클라이언트 코드가 손상될 위험이 있습니다.
형식의 직렬화 가능성 변경 직렬화할 수 없는 형식은 직렬화할 수 없으며 그 반대의 경우도 마찬가지입니다.
메서드에서 다른 예외를 throw합니다.
멤버 정의가 이 가능성을 높이고 클라이언트에서 알 수 없는 값을 처리하는 방법을 명확하게 나타내지 않는 한 메서드의 반환 값 범위를 변경합니다.
대부분의 버그를 수정합니다. 형식의 소비자는 기존 동작을 사용합니다.

구성 요소, 형식 또는 멤버가 보장으로 Exchange 표시된 후에는 해당 구성 요소를 변경하거나 None변경할 Stable 수 없습니다.

일반적으로 교환 형식은 공용 인터페이스에서 일반적으로 사용되는 기본 형식(예: Int32 String .NET) 및 인터페이스(예: IList<T>, IEnumerable<T>및 IComparable<T>)입니다.

Exchange 형식은 호환성으로 Exchange 표시된 다른 형식만 공개적으로 노출할 수 있습니다. 또한 교환 유형은 변경되기 쉬운 Windows API의 동작에 따라 달라질 수 없습니다.

구성 요소 보장

다음 표에서는 구성 요소의 특성 및 사용이 호환성 보장에 미치는 영향을 나타냅니다.

구성 요소 특성	Exchange	안정	나란히	없음
독립적으로 버전이 있는 구성 요소 간의 인터페이스에서 사용할 수 있습니다.	Y	N	N	N
독립적으로 버전이 있는 어셈블리에서 (비공개로) 사용할 수 있습니다.	Y	Y	Y	N
단일 애플리케이션 도메인의 여러 버전이 있을 수 있습니다.	N	Y	Y	Y
호환성이 손상되는 변경을 수행할 수 있습니다.	N	N	Y	Y
어셈블리의 특정 여러 버전을 함께 로드할 수 있도록 테스트되었습니다.	N	N	Y	N
호환성이 손상되는 변경을 수행할 수 있습니다.	N	N	N	Y
매우 안전한 호환성이 손상되지 않는 서비스 변경 내용을 적용할 수 있습니다.	Y	Y	Y	Y

특성 적용

어셈블리, 형식 또는 형식 멤버에 적용 ComponentGuaranteesAttribute 할 수 있습니다. 해당 애플리케이션은 계층적입니다. 즉, 기본적으로 어셈블리 수준에서 특성의 속성에 의해 Guarantees 정의된 보장은 어셈블리의 모든 형식과 해당 형식의 모든 멤버에 대한 보장을 정의합니다. 마찬가지로, 보장이 형식에 적용되는 경우 기본적으로 형식의 각 멤버에도 적용됩니다.

이 상속된 보장은 개별 형식 및 형식 멤버에 적용하여 재정의 ComponentGuaranteesAttribute 할 수 있습니다. 그러나 기본값을 재정의하면 보증만 약화할 수 있습니다. 그들은 그것을 강화할 수 없습니다. 예를 들어 어셈블리가 보장으로 None 표시된 경우 해당 형식과 멤버는 호환성을 보장하지 않으며 어셈블리의 형식 또는 멤버에 적용되는 다른 보장은 무시됩니다.

보증 테스트

속성은 Guarantees 특성으로 표시된 열거형의 ComponentGuaranteesOptions 멤버를 FlagsAttribute 반환합니다. 즉, 잠재적으로 알 수 없는 플래그를 마스킹하여 관심 있는 플래그를 테스트해야 합니다. 예를 들어 다음 예제에서는 형식이 로 표시되는 Stable지 여부를 테스트합니다.

// 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

다음 예제에서는 형식이 로 Stable Exchange표시되는지 여부를 테스트합니다.

// 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

다음 예제에서는 형식이 (즉, 둘 다 Stable 또는 Exchange)로 None 표시된 시저를 테스트합니다.

// 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