미리 보기 API
.NET 플랫폼은 호환성을 중요하게 생각합니다. 따라서 라이브러리 에코시스템은 특히 API와 관련하여 호환성이 손상되는 변경을 방지하는 경향이 있습니다.
그럼에도 불구하고 API를 디자인할 때는 사용자로부터 피드백을 수집하고 필요한 경우 해당 피드백에 따라 API를 변경하는 것이 중요합니다. 놀라움을 방지하려면 사용자가 안정적인 것으로 간주되는 API와 아직 활성 개발 중이며 변경될 수 있는 API를 이해하는 것이 중요합니다.
API가 미리 보기 형식으로 표현할 수 있는 여러 가지 방법이 있습니다.
전체 구성 요소는 미리 보기로 간주됩니다.
- .NET 런타임의 미리 보기 릴리스에 노출됨
- 시험판 NuGet 패키지에 노출됨
그렇지 않은 경우 안정적인 구성 요소는 특히 특정 API를 미리 보기로 표시합니다.
이 문서에서는 이러한 옵션 중에서 선택하는 방법과 각 옵션의 작동 방식을 설명합니다.
.NET 런타임 미리 보기
라이브 라이선스가 있는 릴리스 후보(RC)를 제외하고 .NET 런타임 및 SDK의 미리 보기 버전은 지원되지 않습니다.
따라서 .NET 미리 보기의 일부로 추가된 모든 API는 미리 보기가 받는 피드백에 따라 변경될 수 있는 것으로 간주됩니다. .NET 런타임 미리 보기를 사용하려면 새 프레임워크 버전을 명시적으로 대상으로 지정해야 합니다. 이렇게 하면 변경될 수 있는 API를 사용하는 데 동의를 암시적으로 표현합니다.
시험판 NuGet 패키지
NuGet 패키지는 안정적이거나 시험판으로 표시될 수 있습니다. 즉, 패키지에 시험판 접미사가 있습니다. 예를 들어 System.Text.Json 9.0.0-preview.2.24128.5에는 시험판 접미사 preview.2.24128.5이(가) 있습니다.
패키지 작성자는 일반적으로 시험판 패키지를 지원하지 않으며 얼리어답터로부터 피드백을 수집하는 수단으로 사용합니다.
CLI 또는 UI를 통해 패키지를 설치할 때 일반적으로 시험판 설치 여부를 명시적으로 표시해야 하며, 변경될 수 있는 API를 사용하는 데 대한 동의를 암시적으로 표현해야 합니다.
RequiresPreviewFeaturesAttribute
.NET 6부터 플랫폼에는 RequiresPreviewFeaturesAttribute 특성이 포함됩니다.
이 특성은 런타임, C# 컴파일러 및 라이브러리를 포함하여 스택 전체에서 미리 보기 동작이 필요한 API에 사용됩니다. 이 특성으로 표시된 API를 사용하는 경우 프로젝트에서 <EnablePreviewFeatures>true</EnablePreviewFeatures>을(를) 설정하지 않는 한 빌드 오류가 발생합니다. 해당 속성을 true(으)로 설정하면 <LangVersion>Preview</LangVersion>도 설정되어 미리 보기 언어 기능을 사용할 수 있습니다.
.NET 팀은 .NET 6의 RequiresPreviewFeaturesAttribute 특성을 사용하여 제네릭 수학을 테스트했는데, 당시 미리 보기 상태였던 정적 인터페이스 멤버가 필요했기 때문입니다.
ExperimentalAttribute
.NET 8에는 런타임 또는 언어 미리 보기 기능이 필요하지 않고 지정된 API가 아직 안정적이지 않음을 나타내는 ExperimentalAttribute이(가) 추가되었습니다.
실험적 API에 대해 빌드할 때 컴파일러는 오류를 생성합니다. 실험적으로 표시된 각 기능에는 별도의 진단 ID가 있습니다. 사용에 대한 동의를 표시하려면 특정 진단을 표시하지 않습니다. 진단을 표시하지 않는 방법을 통해 이 작업을 수행할 수 있지만 권장되는 방법은 프로젝트의 <NoWarn> 속성에 진단을 추가하는 것입니다.
각 실험적 기능에는 별도의 ID가 있으므로 하나의 실험적 기능 사용에 동의해도 다른 기능을 사용하는 것에 동의하지 않습니다.
자세한 내용은 실험적 기능을 참조 하세요.
옵션 중에서 선택
라이브러리 개발자는 시험판 NuGet 패키지만 사용하거나 API를 [Experimental](으)로 표시해야 합니다.
패키지의 시험판 버전에 도입된 새 API의 경우 아무 작업도 수행할 필요가 없습니다. 패키지는 이미 미리 보기 품질을 표현합니다.
일부 미리 보기 품질 API가 포함된 안정적인 패키지를 제공하려면
[Experimental]을(를) 사용하여 해당 API를 표시해야 합니다. 사용자 고유의 진단 ID를 사용하고 해당 기능에 맞게 지정해야 합니다. 독립적인 기능이 여러 개인 경우 여러 ID를 사용하는 것이 좋습니다.
[RequiresPreviewFeatures] 특성은 .NET 플랫폼 자체의 구성 요소에만 사용됩니다. 또한 런타임 및 언어 미리 보기 기능이 필요한 API에만 사용됩니다. 미리 보기에 있는 API인 경우 .NET 플랫폼은 [Experimental] 특성을 사용합니다.
이 규칙의 예외는 안정적인 라이브러리를 빌드하고 런타임 또는 언어 미리 보기 동작에 따라 달라지는 특정 기능을 노출하려는 경우입니다. 이 경우 해당 기능의 진입점으로 [RequiresPreviewFeatures]을(를) 사용해야 합니다. 그러나 이러한 API의 사용자도 모든 런타임, 라이브러리 및 언어 미리 보기 동작에 노출되는 미리 보기 기능을 켜야 한다는 점을 고려해야 합니다.
.NET