버전 적응 코드

적응형 UI를 만드는 방법과 비슷하게 적응 코드를 작성하는 방법을 생각할 수 있습니다. 가장 낮은 OS 버전에서 실행되도록 기본 코드를 디자인한 다음, 새 기능을 사용할 수 있는 상위 버전에서 앱이 실행되는 것을 감지하면 기능을 추가합니다.

API 계약 및 Visual Studio 구성에 대한 ApiInformation배경 정보는 버전 적응형 앱을 참조하세요.

사전 요구 사항

  • Windows 앱 SDK 프로젝트(패키지 또는 패키지되지 않음)입니다. 빠른 시작: 첫 번째 WinUI 3 앱 만들기를 참조하세요.
  • ApiInformation 검사는 Windows.* 네임스페이스 형식에만 적용되므로, WinRT(Windows 런타임) 형식 시스템에 익숙해야 합니다.

런타임 API 검사

호출하려는 API가 있는지 확인하려면 코드의 조건문에서 Windows.Foundation.Metadata.ApiInformation 클래스를 사용하세요. 이 조건은 앱이 실행되는 모든 위치에서 평가되지만 API가 있고 호출할 true 수 있는 디바이스에서만 평가됩니다.

Important

ApiInformation 검사는 Windows.* 네임스페이스의 Windows 런타임 형식에서만 작동합니다. 이들은 WinUI 유형(Microsoft.UI.Xaml.*)을 감지하지 못하는데, 그 유형은 OS가 아니라 Windows 앱 SDK 프레임워크 패키지의 일부이며, ApiInformation에서 쿼리할 수 있는 WinRT 메타데이터로 등록되어 있지 않기 때문입니다. #if 전처리기 지시문은 여기서도 도움이 되지 않습니다. 즉, 앱이 실제로 실행 중인 OS 또는 SDK 버전을 기반으로 런타임이 아니라 대상 프레임워크에 따라 컴파일 시간에 평가됩니다. WinUI 기능을 조건부로 켜려면 앱이 빌드된 Windows 앱 SDK 버전(버전 적응 앱 참조)을 확인하거나, 호출을 try/catch로 래핑하고 런타임에 실패할 경우 대체합니다.

팁 (조언)

수많은 런타임 API 검사는 앱의 성능에 영향을 줄 수 있습니다. 검사를 한 번 수행하고 결과를 캐시한 다음 앱 전체에서 캐시된 결과를 사용합니다.

적응 코드 옵션

적응 코드를 만드는 방법에는 두 가지가 있습니다.

  • 앱 코드 — 코드 비하인드에서 런타임 API 확인을 사용합니다. 대부분의 시나리오에 권장되는 방법입니다.
  • 상태 트리거 - API의 존재에 따라 시각적 상태를 활성화하는 확장 가능한 상태 트리거를 사용합니다. 시각적 상태에 연결된 OS 버전 간에 단순 속성 또는 열거형 변경이 있는 경우 상태 트리거를 사용합니다.

예: 열거형 값 확인하기

이 예제에서는 특정 열거형 값을 사용하기 전에 존재하는지 여부를 확인하는 방법을 보여줍니다. 값이 없으면 코드가 대체 항목으로 대체됩니다. EnergySaverStatus 및 PowerManager은 Windows.System.Power 네임스페이스의 정식 Windows 런타임 형식이므로 ApiInformation에서 이를 올바르게 쿼리할 수 있습니다.

if (ApiInformation.IsEnumNamedValuePresent(
    "Windows.System.Power.EnergySaverStatus", "On"))
{
    if (PowerManager.EnergySaverStatus == EnergySaverStatus.On)
    {
        // Reduce background work to save battery.
        ReduceBackgroundActivity();
    }
}
else
{
    // Energy Saver status isn't available on this OS version; skip the check.
}

void ReduceBackgroundActivity()
{
    // Pause non-essential timers, syncs, and animations here.
}

Important

API 검사 결과를 캐시하는 경우 앱 전체에서 캐시된 값을 일관되게 사용합니다. 여러 위치에서 검사를 반복하지 마세요. 한 번 확인하고, 결과를 저장하고, 어디서나 참조하세요.

예: 메서드 확인

호출하기 전에 특정 메서드를 사용할 수 있는지 확인하는 데 사용합니다 IsMethodPresent .

DisplayRequest displayRequest = new DisplayRequest();

if (ApiInformation.IsMethodPresent(
    "Windows.System.Display.DisplayRequest", "RequestActive"))
{
    displayRequest.RequestActive();
}

예: 속성이 있는지 확인

특정 속성을 읽기 전에 사용할 수 있는지 확인하는 데 사용합니다 IsPropertyPresent .

if (ApiInformation.IsPropertyPresent(
    "Windows.System.Power.PowerManager", "RemainingChargePercent"))
{
    int chargePercent = PowerManager.RemainingChargePercent;
}

모범 사례

연습 안내
정적 문자열 사용 API 이름을 ApiInformation확인할 때 런타임 형식 로드 문제를 방지하기 위해 .NET 리플렉션 대신 하드 코딩된 문자열을 사용합니다.
캐시 결과 시작할 때 각 API 검사를 한 번 수행하고 다시 사용할 결과를 저장합니다.
최소 버전 낮게 유지 프로젝트의 최소 버전을 가장 광범위한 대상 그룹에 도달하기 위해 최대한 낮게 설정하고 적응 코드를 사용하여 최신 OS 버전에서 기능을 표시합니다.
최소 버전에서 테스트 항상 지원되는 최소 OS 버전을 테스트하여 대체 경로가 올바르게 작동하는지 확인합니다.

관련 콘텐츠

  • Last updated on