アダプティブ アプリのバージョン:新しい Api を使用して、以前のバージョンとの互換性を維持しながらVersion adaptive apps: Use new APIs while maintaining compatibility with previous versions

Windows 10 SDK の各リリースには、ユーザーが利用したくなるような魅力的な新機能が追加されています。Each release of the Windows 10 SDK adds exciting new functionality that you'll want to take advantage of. ただし、すべてのユーザーがデバイスを最新バージョンの Windows 10 に同時に更新するわけではないため、できるだけ幅広いデバイスでアプリが動作するようにする必要があります。However, not all your customers will update their devices to the latest version of Windows 10 at the same time, and you want to make sure your app works on the broadest possible range of devices. ここでは、アプリが以前のバージョンの Windows 10 で動作するだけでなく、最新の更新プログラムがインストールされたデバイスでアプリを実行したときに新機能を利用できるように、アプリを設計する方法について説明します。Here, we show you how to design your app so that it runs on earlier versions of Windows 10, but also takes advantage of new features whenever your app runs on a device with the latest update installed.

できるだけ幅広い Windows 10 デバイスをアプリでサポートするには、3 つの手順を実行する必要があります。There are 3 steps to take to make sure your app supports the broadest range of Windows 10 devices.

  • まず、最新の API を対象とするように Visual Studio プロジェクトを構成します。First, configure your Visual Studio project to target the latest APIs. これは、アプリをコンパイルするときの処理に影響します。This affects what happens when you compile your app.
  • 次に、ランタイム チェックを実行して、アプリが実行されているデバイスに存在する API だけを呼び出すようにします。Second, perform runtime checks to ensure that you only call APIs that are present on the device your app is running on.
  • 最後に、最小バージョンとターゲット バージョンの Windows 10 でアプリをテストします。Third, test your app on the Minimum Version and the Target Version of Windows 10.

Visual Studio プロジェクトの構成Configure your Visual Studio project

複数の Windows 10 バージョンをサポートするための最初の手順は、Visual Studio プロジェクトで、サポートされるターゲット最小の OS/SDK バージョンを指定することです。The first step in supporting multiple Windows 10 versions is to specify the Target and Minimum supported OS/SDK versions in your Visual Studio project.

  • Target:SDK のバージョン Visual Studio は、アプリのコードをコンパイルし、に対するすべてのツールを実行します。Target: The SDK version that Visual Studio compiles your app code and run all tools against. この SDK バージョンに含まれているすべての API とリソースは、コンパイル時にアプリ コードで使うことができます。All APIs and resources in this SDK version are available in your app code at compile time.
  • 最小:アプリで実行できます (およびストアに配置されます)、最も古い OS バージョンと Visual Studio は、アプリのマークアップ コードをコンパイルするバージョンをサポートする SDK のバージョン。Minimum: The SDK version that supports the earliest OS version that your app can run on (and will be deployed to by the store) and the version that Visual Studio compiles your app markup code against.

実行時には展開先の OS バージョンに対してアプリが実行されるため、そのバージョンで利用できないリソースを使ったり、そのような API を呼び出したりすると、アプリによって例外がスローされます。During runtime your app will run against the OS version that it is deployed to, so your app will throw exceptions if you use resources or call APIs that are not available in that version. ランタイム チェックを使って適切な API を呼び出す方法については、この記事の後半で説明します。We show you how to use runtime checks to call the correct APIs later in this article.

ターゲットと最小の設定では、OS/SDK バージョンの範囲の両端を指定します。The Target and Minimum settings specify the ends of a range of OS/SDK versions. ただし、最小バージョンでアプリをテストした場合、最小とターゲット間のすべてのバージョンでアプリが実行されるようになります。However, if you test your app on the minimum version, you can be sure it will run on any versions between the Minimum and Target.

ヒント

Visual Studio では API の互換性についての警告は表示されません。Visual Studio does not warn you about API compatibility. ご自身の責任で最小とターゲットの間にあるすべての OS バージョン (最小とターゲットのバージョンを含む) でアプリが期待どおりに実行されることをテストし、確認してください。It is your responsibility to test and ensure that your app performs as expected on all OS versions between and including the Minimum and Target.

Visual Studio 2015 Update 2 以降で新しいプロジェクトを作成すると、アプリがサポートしているターゲット バージョンと最小バージョンを設定するように求められます。When you create a new project in Visual Studio 2015, Update 2 or later, you are prompted to set the Target and Minimum versions that your app supports. 既定では、ターゲット バージョンはインストール済みの SDK の中で最も高いバージョンで、最小バージョンはインストール済みの SDK バージョンの中で最も低いバージョンです。By default, the Target Version is the highest installed SDK version, and the Minimum Version is the lowest installed SDK version. コンピューターにインストールされている SDK バージョンからのみ、ターゲットと最小を選ぶことができます。You can choose Target and Minimum only from SDK versions that are installed on your machine.

Visual Studio でターゲット SDK を設定する

通常、既定値のままにすることをお勧めします。We typically recommend that you leave the defaults. ただし、SDK のプレビュー版をインストールしていて、運用コードを記述している場合、ターゲット バージョンを Preview SDK から最新の公式の SDK バージョンに変更する必要があります。However, if you have a Preview version of the SDK installed and you are writing production code, you should change the Target Version from the Preview SDK to the latest official SDK version.

Visual Studio で既に作成済みのプロジェクトの最小バージョンとターゲット バージョンを変更するには、[プロジェクト]、[プロパティ]、[アプリケーション] タブ、[ターゲット] の順に移動します。To change the Minimum and Target version for a project that has already been created in Visual Studio, go to Project -> Properties -> Application tab -> Targeting.

Visual Studio でターゲット SDK を変更する

参考のために、各 SDK のビルド番号を次の表に示します。For reference, the following table shows the build numbers for each SDK.

フレンドリ名Friendly name バージョンVersion OS/SDK ビルドOS/SDK build
RTMRTM 15071507 1024010240
11 月の更新プログラムNovember Update 15111511 1058610586
Anniversary UpdateAnniversary Update 16071607 1439314393
Creators UpdateCreators Update 17031703 1506315063
Fall Creators UpdateFall Creators Update 17091709 1629916299
April 2018 UpdateApril 2018 Update 18031803 1713417134
2018年 10 月 UpdateOctober 2018 Update 18091809 1776317763
2019 の月の更新May 2019 Update 19031903 1836218362

SDK のすべてのリリース版は、「Windows SDK とエミュレーターのアーカイブ」からダウンロードできます。You can download any released version of the SDK from the Windows SDK and emulator archive. 最新の Windows Insider Preview SDK は、Windows Insider サイトの「開発者向け」セクションからダウンロードできます。You can download the latest Windows Insider Preview SDK from the developer section of the Windows Insider site.

Windows 10 更新プログラムの詳細については、次を参照してください。 Windows 10 のリリース情報します。For more info about Windows 10 updates, see Windows 10 release information. Windows 10 のサポート ライフ サイクルに関する重要な情報は、次を参照してください。、 Windows ライフ サイクル ファクト シートします。For important information about the Windows 10 support lifecycle, see the Windows lifecycle fact sheet.

API チェックの実行Perform API checks

バージョン アダプティブ アプリの要は、API コントラクトと ApiInformation クラスの組み合わせにあります。The key to version adaptive apps is the combination of API contracts and the ApiInformation class. このクラスは、さまざまなデバイスと OS バージョンで、指定した API コントラクト、型、またはメンバーが存在し、安全に API を呼び出すことができるかどうかを検出します。This class lets you detect whether a specified API contract, type, or member is present so that you can safely make API calls across a variety of devices and OS versions.

API コントラクトAPI contracts

デバイス ファミリ内の API のセットは、API コントラクトと呼ばれる小項目に分類されます。The set of APIs within a device family is broken down into subdivisions known as API contracts. API コントラクトの存在をテストするには、ApiInformation.IsApiContractPresent メソッドを使うことができます。You can use the ApiInformation.IsApiContractPresent method to test for the presence of an API contract. これは、すべてが API コントラクトの同じバージョンに存在する多数の API の存在をテストする場合に便利です。This is useful if you want to test for the presence of many APIs that all exist in the same version of an API contract.

    bool isScannerDeviceContract_1_Present =
        Windows.Foundation.Metadata.ApiInformation.IsApiContractPresent
            ("Windows.Devices.Scanners.ScannerDeviceContract", 1);

API コントラクトとは何でしょうか。What’s an API contract? 基本的に、API コントラクトとは機能を表します。これは、何らかの特定の機能を構成する関連 API のセットです。Essentially, an API contract represents a feature – a set of related APIs that together deliver some particular functionality. たとえば、ある API コントラクトは、2 つのクラス、5 つのインターフェイス、1 つの構造体、2 つの列挙体などを含む API のセットを表している可能性があります。A hypothetical API contract could represent a set of APIs containing two classes, five interfaces, one structure, two enums, and so on.

論理的に関連する型は API コントラクトにグループ化され、Windows 10 以降、すべての Windows ランタイム API は何らかの API コントラクトに属しています。Logically related types are grouped into an API contract, and starting with Windows 10, every Windows Runtime API is a member of some API contract. API コントラクトでは、デバイス上の特定の機能や API の存在がチェックされます。デバイスの機能のチェックは、特定のデバイスまたは OS をチェックするよりも効率的に行われます。With API Contracts, you are checking for the availability of a specific feature or API on the device, effectively checking a device’s capabilities rather than checking for a specific device or OS. API コントラクト内のいずれかの API を実装するプラットフォームには、同じ API コントラクト内のすべての API を実装する必要があります。A platform that implements any API in an API contract is required to implement every API in that API contract. つまり、実行中の OS が特定の API コントラクトをサポートしているかどうかをテストし、サポートしていると判明した場合は、その API コントラクト内のすべての API を個別にチェックせずに呼び出すことができます。This means you can test whether the running OS supports a particular API contract and, if it does, call any of the APIs in that API contract without checking each one individually.

最も大規模で最もよく使われる API コントラクトは Windows.Foundation.UniversalApiContract です。The largest and most commonly used API contract is the Windows.Foundation.UniversalApiContract. これには、ユニバーサル Windows プラットフォームの API の大部分が含まれています。It contains the majority of the APIs in the Universal Windows Platform. デバイス ファミリの拡張 SDK および API コントラクト」ドキュメントでは、利用できるさまざまな API コントラクトについて説明しています。The Device Family Extension SDKs and API contracts documentation describes the variety of API contracts available. ほとんどの API コントラクトは、機能的に関連のある API のセットを表していることがわかります。You’ll see that most of them represent a set of functionally related APIs.

注意

SDK のインストール フォルダーにある 'Platform.xml' ファイルに API コントラクトのサポートに関する情報を見つけることができますもまだ文書化されていないプレビュー Windows ソフトウェア開発キット (SDK) をインストールした場合 '(Program Files (x86)) \Windows Kits\10\Platforms<プラットフォーム ><SDK バージョン > \Platform.xml'。If you have a preview Windows Software Development Kit (SDK) installed that isn’t documented yet, you can also find information about API contract support in the ‘Platform.xml’ file located in the SDK installation folder at ‘(Program Files (x86))\Windows Kits\10\Platforms<platform><SDK version>\Platform.xml’.

バージョン アダプティブ コードと条件付き XAMLVersion adaptive code and conditional XAML

すべてのバージョンの Windows 10 では、コード内の条件式で ApiInformation クラスを使って、呼び出そうとしている API が存在するかどうかをテストできます。In all versions of Windows 10, you can use the ApiInformation class in a condition in your code to test for the presence of the API you want to call. IsTypePresent、IsEventPresent、IsMethodPresent、IsPropertyPresent など、このクラスのさまざまなメソッドをアダプティブ コードで使って、必要に応じた精度で API をテストできます。In your adaptive code, you can use various methods of the class, such as IsTypePresent, IsEventPresent, IsMethodPresent, and IsPropertyPresent, to test for APIs at the granularity you need.

詳細と例については、「 バージョン アダプティブ コード 」をご覧ください。For more info and examples, see Version adaptive code.

アプリの最小バージョンがビルド 15063 (Creators Update) 以降の場合は、条件付き XAML を使って、プロパティの設定やオブジェクトのインスタンス化をマークアップで行うことができます。この場合、分離コードを使う必要はありません。If your apps Minimum Version is build 15063 (Creators Update) or later, you can use conditional XAML to set properties and instantiate objects in markup without needing to use code behind. 条件付き XAML は、マークアップで ApiInformation.IsApiContractPresent メソッドを使う方法を提供するものです。Conditional XAML provides a way to use the ApiInformation.IsApiContractPresent method in markup.

詳しい説明と例については、「 条件付き XAML 」をご覧ください。For more info and examples, see Conditional XAML.

バージョン アダプティブ アプリのテストTest your version adaptive app

バージョン アダプティブ コードや条件付き XAML を使ってバージョン アダプティブ アプリを作成する場合は、最小バージョンの Windows 10 を実行しているデバイスとターゲット バージョンを実行しているデバイスでアプリをテストする必要があります。When you use version adaptive code or conditional XAML to write a version adaptive app, you need to test it on a device running the Minimum Version and on a device running the Target Version of Windows 10.

条件付きコードのすべてのパスを 1 台のデバイスでテストすることはできません。You can't test all conditional code paths on a single device. すべてのコード パスを確実にテストするために、サポートされる最小の OS バージョンを実行しているリモート デバイス (または仮想マシン) でアプリを展開してテストする必要があります。To ensure that all code paths are tested, you need to deploy and test your app on a remote device (or virtual machine) running the minimum supported OS version. リモート デバッグについて詳しくは、「UWP アプリの展開とデバッグ」をご覧ください。For more info about remote debugging, see Deploying and debugging UWP apps.