バージョン適応コード

アダプティブ UI の作成に関する考え方と同様に、アダプティブコードの記述について考えることができます。最小の OS バージョンで実行するように基本コードを設計し、新しい機能が利用可能な上位バージョンでアプリが実行されていることを検出したときに機能を追加します。

ApiInformation、API コントラクト、およびVisual Studioの構成の背景情報については、「バージョンアダプティブアプリ」を参照してください。

前提条件

Windows アプリ SDK プロジェクト (パッケージ化またはパッケージ化されていない)。「クイックスタート: 初めての WinUI 3 アプリを作成する」を参照してください。
ApiInformation チェックは Windows.* 名前空間の型にのみ適用されるため、Windows ランタイム (WinRT) 型システムに精通していること。

ランタイム API のチェック

呼び出そうとしている API が存在するかどうかを確認するために、コード内の条件式で Windows.Foundation.Metadata.ApiInformation クラスを使用します。この条件は、アプリの実行場所を問わず評価されますが、API が存在し、呼び出し可能なデバイスでのみ true に評価されます。

Important

ApiInformationチェックは、Windows.*名前空間内のWindows ランタイム型に対してのみ機能します。これらの型は OS ではなくWindows アプリ SDK フレームワークパッケージの一部であり、クエリできる WinRT メタデータとして登録されていないため、WinUI 型 (Microsoft.UI.Xaml.*) は検出ApiInformation。 #if プリプロセッサディレクティブはここでも役に立ちません。これらは、アプリケーションが実際に実行されている OS や SDK のバージョンに基づいて実行時に評価されるのではなく、ターゲットフレームワークに基づいてコンパイル時に評価されるためです。 WinUI 機能を条件付きで点灯するには、アプリがビルドされたWindows アプリ SDKバージョンを確認するか (バージョンアダプティブアプリを参照)、呼び出しを try/catch でラップし、実行時に失敗した場合はフォールバックします。

Tip

多数のランタイム API チェックがアプリのパフォーマンスに影響する可能性があります。チェックを 1 回実行し、結果をキャッシュしてから、アプリ全体でキャッシュされた結果を使用します。

アダプティブコードオプション

アダプティブコードを作成するには、次の 2 つの方法があります。

アプリコード — コードビハインドではランタイム 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 チェックの結果をキャッシュする場合は、そのキャッシュされた値をアプリ全体で一貫して使用します。複数の場所でチェックを繰り返さないでください。1 回確認し、結果を格納し、あらゆる場所で参照します。

例: メソッドを確認する

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;
}

ベストプラクティス

演習	Guidance
静的文字列を使用する	`ApiInformation` で API 名を確認する際は、ランタイムの型読み込みの問題を回避するため、.NET リフレクションではなく、ハードコーディングされた文字列を使用してください
キャッシュの結果	起動時に各 API チェックを 1 回実行し、結果を保存して再利用する
最小バージョンを低く保つ	プロジェクトの最小バージョンをできるだけ低く設定して最も幅広いユーザーにリーチし、アダプティブコードを使用して新しい OS バージョンの機能を明るくする
最小バージョンでテストする	サポートされている最小バージョンの OS で常にテストして、フォールバックパスが正しく動作することを確認します

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-11