미리 보기 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
RequiresPreviewFeaturesAttribute 특성은 런타임, C# 컴파일러 및 라이브러리를 포함하여 스택 전체에서 미리 보기 동작이 필요한 API에 사용됩니다. 이 특성으로 표시된 API를 사용하는 경우 프로젝트 파일에 속성 <EnablePreviewFeatures>true</EnablePreviewFeatures>포함되어 있지 않으면 빌드 오류가 발생합니다. 해당 속성을 true으로 설정하면 <LangVersion>Preview</LangVersion>도 설정되어 미리 보기 언어 기능을 사용할 수 있습니다.
예를 들어 .NET 6에서 제네릭 수학 라이브러리는 당시 미리 보기 상태였던 정적 인터페이스 멤버가 필요했기 때문에 RequiresPreviewFeaturesAttribute 표시되었습니다.
ExperimentalAttribute
.NET 8은 런타임 또는 언어 미리 보기 기능이 필요하지 않고 지정된 API가 아직 안정적이지 않음을 나타내는 ExperimentalAttribute추가되었습니다.
실험적 API에 대해 빌드할 때 컴파일러는 오류를 생성합니다. 실험적으로 표시된 각 기능에는 별도의 진단 ID가 있습니다. 실험적인 API 사용에 동의하려면 특정 진단을 억제하세요. 진단을 표시하지 않는 방법을 통해 수행할 수 있지만 프로젝트의 <NoWarn> 속성에 진단을 추가하는 것이 좋습니다.
각 실험적 기능에는 별도의 ID가 있으므로 하나의 실험적 기능 사용에 동의해도 다른 기능을 사용하는 것에 동의하지 않습니다.
자세한 내용은 실험적 기능 및 일반 특성대한 C# 가이드의 문서를 참조하세요.
라이브러리 개발자를 위한 지침
라이브러리 개발자는 일반적으로 API가 사전 공개 상태에 있다는 것을 다음 두 가지 방법 중 하나로 표현해야 합니다.
- 패키지의 시험판 버전에 도입된 새 API의 경우 아무 작업도 수행할 필요가 없습니다. 패키지는 이미 미리 보기 품질을 표현합니다.
- 일부 미리 보기 품질 API가 포함된 안정적인 패키지를 제공하려면
[Experimental]사용하여 해당 API를 표시해야 합니다. 사용자 고유의 진단 ID 사용하고 해당 기능과 관련이 있는지 확인합니다. 독립적인 기능이 여러 개인 경우 여러 ID를 사용하는 것이 좋습니다.
[RequiresPreviewFeatures] 특성은 .NET 플랫폼 자체의 구성 요소에만 사용됩니다. 심지어 런타임 및 언어 미리 보기 기능이 필요한 API에만 사용됩니다. 미리 보기에 있는 API인 경우 .NET 플랫폼은 [Experimental] 특성을 사용합니다.
이 규칙의 예외는 안정적인 라이브러리를 빌드하고 런타임 또는 언어 미리 보기 동작에 따라 달라지는 특정 기능을 노출하려는 경우입니다. 이 경우 해당 기능의 진입점에 [RequiresPreviewFeatures] 사용해야 합니다. 그러나 이러한 API의 사용자도 모든 런타임, 라이브러리 및 언어 미리 보기 동작에 노출되는 미리 보기 기능을 켜야 한다는 점을 고려해야 합니다.
.NET