バージョンアダプティブコード

[アーティクル]
03/31/2023

アダプティブコードの記述については、アダプティブ UI の作成についての考え方と同じように考えることができます。最小画面で実行するように基本 UI を設計し、より大きな画面でアプリが実行されていることを検出したときに要素を移動または追加できます。アダプティブコードの場合、最小の OS バージョンで実行するように基本コードを記述し、新機能が提供されているより高いバージョンでアプリが実行されていることを検出したときに、機能を手動で選んで追加できます。

ApiInformation に関する重要な背景情報、API コントラクト、Visual Studio の構成については、「バージョンアダプティブアプリ」をご覧ください。

ランタイム API チェック

呼び出す API が存在するかどうかをテストするには、コード内の条件で Windows.Foundation.Metadata.ApiInformation クラスを使います。この条件は、アプリがどこで実行された場合でも評価されますが、API が存在して呼び出すことができるデバイスでのみ true と評価されます。これにより、特定の OS バージョンでのみ利用できる API を使うアプリを作成するためのバージョンアダプティブコードを記述できます。

ここでは、Windows Insider Preview の新機能をターゲットにするための具体的な例を示します。 ApiInformation を使用する場合の一般的な概要については、「拡張 SDK でのプログラミング」と、API コントラクトを使った機能の動的な検出に関する記事をご覧ください。

ヒント

さまざまなランタイム API チェックが、アプリのパフォーマンスに影響する可能性があります。それらの例では、チェックをインラインで示します。運用コードでは、チェックを一度実行してから結果をキャッシュし、キャッシュされた結果をアプリ全体で使う必要があります。

サポートされていないシナリオ

ほとんどの場合、アプリの最小バージョンを SDK バージョン 10240 に設定したままにし、アプリがそれより新しいバージョンで実行されたときに、ランタイムチェックを使って新しい API を有効にすることができます。ただし、新機能を使うためにアプリの最小バージョンを上げることが必要になる場合もあります。

アプリの最小バージョンを上げる必要があるのは、以下を使う場合です。

以前のバージョンでは使うことができない機能を必要とする新しい API。サポートされる最小バージョンを、その機能が含まれているバージョンに上げる必要があります。詳しくは、「アプリ機能の宣言」をご覧ください。
generic.xaml に追加された新しいリソースキーのうち、以前のバージョンでは使うことができないリソースキー。実行時に使われる generic.xaml のバージョンは、デバイスで実行されている OS バージョンによって決まります。ランタイム API チェックを使って XAML リソースの有無を確認することはできません。そのため、アプリがサポートする最小バージョンで利用できるリソースキーのみを使う必要があります。そうしないと、XAMLParseException が原因で実行時にアプリがクラッシュします。

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

アダプティブコードを作成するには 2 つの方法があります。ほとんどの場合、アプリのマークアップを最小バージョンで実行するように記述してから、アプリコードを使ってより新しい OS 機能 (存在する場合) を活用します。ただし、表示状態でプロパティを更新する必要があり、OS バージョン間でプロパティ値と列挙値の変更のみがある場合、API の存在に基づいてアクティブ化される拡張可能な状態トリガーを作成できます。

ここで、以下のオプションを比較します。

アプリケーションコード

使う状況:

すべてのアダプティブコードシナリオにお勧めします。ただし、拡張可能なトリガー用に以下に定義されている特定のケースは除きます。

利点:

API の相違をマークアップに結び付ける際の開発者のオーバーヘッドや複雑さを回避できます。

欠点:

デザイナーがサポートされていません。

状態トリガー

使う状況:

OS バージョン間で、ロジックを変更する必要のない、表示状態に関連付けられているプロパティまたは列挙値のみに変更がある場合に使います。

利点:

API の存在に基づいてトリガーされる特定の表示状態を作成できます。
一部のデザイナーサポートを利用できます。

欠点:

カスタムトリガーの使用は表示状態に限定されるため、複雑なアダプティブレイアウトには適していません。
セッターを使って値の変更を指定する必要があるため、単純な変更だけを行うことができます。
カスタム状態トリガーを設定して使うには、非常に細かい設定が必要です。

アダプティブコードの例

このセクションでは、Windows 10 バージョン 1607 (Windows Insider Preview) で新しく追加された API を使うアダプティブコードの例をいくつか示します。

例 1:新しい列挙値

Windows 10 バージョン 1607 では、InputScopeNameValue 列挙体に新しい値のChatWithoutEmoji が追加されています。この新しい入力スコープの入力動作は、Chat 入力スコープ (スペルチェック、オートコンプリート、大文字の自動設定) と同じですが、絵文字ボタンのないタッチキーボードにマップされます。これは、独自の絵文字ピッカーを作成し、タッチキーボードに組み込まれている絵文字ボタンを無効にする場合に便利です。

次の例は、ChatWithoutEmoji 列挙値が存在するかどうかを確認し、存在する場合は TextBox の InputScope プロパティを設定する方法を示しています。アプリが実行されているシステムにこの列挙値が存在しない場合、InputScope は Chat に設定されます。ここに示されているコードは、Page コンストラクターまたは Page.Loaded イベントハンドラーに配置できます。

ヒント

API をチェックするときは、.NET 言語機能を使うのではなく静的な文字列を使います。そうしないと、アプリは定義されていない型にアクセスしようとして、実行時にクラッシュすることがあります。

// Create a TextBox control for sending messages 
// and initialize an InputScope object.
TextBox messageBox = new TextBox();
messageBox.AcceptsReturn = true;
messageBox.TextWrapping = TextWrapping.Wrap;
InputScope scope = new InputScope();
InputScopeName scopeName = new InputScopeName();

// Check that the ChatWithEmoji value is present.
// (It's present starting with Windows 10, version 1607,
//  the Target version for the app. This check returns false on earlier versions.)         
if (ApiInformation.IsEnumNamedValuePresent("Windows.UI.Xaml.Input.InputScopeNameValue", "ChatWithoutEmoji"))
{
    // Set new ChatWithoutEmoji InputScope if present.
    scopeName.NameValue = InputScopeNameValue.ChatWithoutEmoji;
}
else
{
    // Fall back to Chat InputScope.
    scopeName.NameValue = InputScopeNameValue.Chat;
}

// Set InputScope on messaging TextBox.
scope.Names.Add(scopeName);
messageBox.InputScope = scope;

// For this example, set the TextBox text to show the selected InputScope.
messageBox.Text = messageBox.InputScope.Names[0].NameValue.ToString();

// Add the TextBox to the XAML visual tree (rootGrid is defined in XAML).
rootGrid.Children.Add(messageBox);

前の例では、TextBox が作成され、コードにすべてのプロパティが設定されています。ただし、既存の XAML があり、新しい値がサポートされているシステムで InputScope プロパティのみを変更する必要がある場合、次に示すように、XAML を変更せずにその操作を実行できます。 XAML で既定値を Chat に設定しますが、ChatWithoutEmoji 値が存在する場合はコードでそれをオーバーライドします。

XAML

<TextBox x:Name="messageBox"
         AcceptsReturn="True" TextWrapping="Wrap"
         InputScope="Chat"
         Loaded="messageBox_Loaded"/>

private void messageBox_Loaded(object sender, RoutedEventArgs e)
{
    if (ApiInformation.IsEnumNamedValuePresent("Windows.UI.Xaml.Input.InputScopeNameValue", "ChatWithoutEmoji"))
    {
        // Check that the ChatWithEmoji value is present.
        // (It's present starting with Windows 10, version 1607,
        //  the Target version for the app. This code is skipped on earlier versions.)
        InputScope scope = new InputScope();
        InputScopeName scopeName = new InputScopeName();
        scopeName.NameValue = InputScopeNameValue.ChatWithoutEmoji;
        // Set InputScope on messaging TextBox.
        scope.Names.Add(scopeName);
        messageBox.InputScope = scope;
    }

    // For this example, set the TextBox text to show the selected InputScope.
    // This is outside of the API check, so it will happen on all OS versions.
    messageBox.Text = messageBox.InputScope.Names[0].NameValue.ToString();
}

既に具体例があるので、ターゲットバージョンと最小バージョンの設定がどのように適用されるのかを見てみましょう。

これらの例では、XAML またはチェックを含まないコードで Chat 列挙値を使うことができます。これは、Chat 列挙値がサポートされる最小の OS バージョンに存在するためです。

XAML またはチェックを含まないコードで ChatWithoutEmoji 値を使うと、ChatWithoutEmoji 値がターゲットの OS バージョンに存在するためエラーなしでコンパイルされます。また、ターゲットの OS バージョンが含まれたシステムで、エラーなしで実行されます。ただし、アプリが最小バージョンを使っている OS を含むシステムで実行されると、ChatWithoutEmoji 列挙値が存在しないため実行時にクラッシュします。そのため、コードでのみこの値を使って、この値が現在のシステムでサポートされている場合だけ呼び出されるように、ランタイム API チェックにラップする必要があります。

例 2: 新しいコントロール

通常、新しいバージョンの Windows では、プラットフォームに新機能をもたらす新しいコントロールが UWP API サーフェスに追加されています。新しいコントロールを活用するには、ApiInformation.IsTypePresent メソッドを使います。

Windows 10 バージョン 1607 には、MediaPlayerElement と呼ばれる新しいメディアコントロールが導入されています。このコントロールは、MediaPlayer クラスに基づいて作成されているため、バックグラウンドオーディオに簡単に結び付けることができるような機能が追加され、メディアスタックの向上したアーキテクチャを活用しています。

ただし、アプリが Windows 10 バージョン 1607 より古いバージョンを実行しているデバイスで実行される場合、新しい MediaPlayerElement コントロールではなく、MediaElement コントロールを使う必要があります。 ApiInformation.IsTypePresent メソッドを使って実行時に MediaPlayerElement コントロールが存在するかどうかをチェックし、アプリが実行されているシステムに適しているコントロールを読み込むことができます。

この例は、新しい MediaPlayerElement または古い MediaElement を使うアプリを作成する方法を示しています。どちらを使うかは、MediaPlayerElement 型が存在するかどうかによって異なります。このコードでは、UserControl クラスを使って、コントロール、およびそれに関連する UI とコードをコンポーネント化し、OS バージョンに基づいて切り替えることができるようにしています。また、このシンプルな例に必要なものよりも機能的でカスタムの動作を提供するカスタムコントロールを使うこともできます。

MediaPlayerUserControl

MediaPlayerUserControl は、MediaPlayerElement と、フレーム単位でメディアを飛ばすために使われるいくつかのボタンをカプセル化します。 UserControl を使うと、これらのコントロールを単一のエンティティとして扱って、以前のシステムの MediaElement と簡単に切り替えることができます。このユーザーコントロールは、MediaPlayerElement が存在するシステムでのみ使う必要があるため、このユーザーコントロール内のコードでは ApiInformation チェックを使いません。

Note

この例をシンプルなままにし、集中して取り組むために、フレームステップボタンはメディアプレーヤーの外部に配置されています。ユーザーエクスペリエンスを向上するためには、MediaTransportControls をカスタマイズしてカスタムボタンを含める必要があります。詳しくは、「カスタムトランスポートコントロールを作成する」をご覧ください。

XAML

<UserControl
    x:Class="MediaApp.MediaPlayerUserControl"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MediaApp"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    d:DesignHeight="300"
    d:DesignWidth="400">

    <Grid x:Name="MPE_grid>
        <Grid.RowDefinitions>
            <RowDefinition/>
            <RowDefinition Height="Auto"/>
        </Grid.RowDefinitions>
        <StackPanel Orientation="Horizontal" 
                    HorizontalAlignment="Center" Grid.Row="1">
            <RepeatButton Click="StepBack_Click" Content="Step Back"/>
            <RepeatButton Click="StepForward_Click" Content="Step Forward"/>
        </StackPanel>
    </Grid>
</UserControl>

using System;
using Windows.Media.Core;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;

namespace MediaApp
{
    public sealed partial class MediaPlayerUserControl : UserControl
    {
        public MediaPlayerUserControl()
        {
            this.InitializeComponent();
            
            // The markup code compiler runs against the Minimum OS version so MediaPlayerElement must be created in app code
            MPE = new MediaPlayerElement();
            Uri videoSource = new Uri("ms-appx:///Assets/UWPDesign.mp4");
	        MPE.Source = MediaSource.CreateFromUri(videoSource);
	        MPE.AreTransportControlsEnabled = true;
            MPE.MediaPlayer.AutoPlay = true;

            // Add MediaPlayerElement to the Grid
            MPE_grid.Children.Add(MPE);

        }

        private void StepForward_Click(object sender, RoutedEventArgs e)
        {
            // Step forward one frame, only available using MediaPlayerElement.
            MPE.MediaPlayer.StepForwardOneFrame();
        }

        private void StepBack_Click(object sender, RoutedEventArgs e)
        {
            // Step forward one frame, only available using MediaPlayerElement.
            MPE.MediaPlayer.StepForwardOneFrame();
        }
    }
}

MediaElementUserControl

MediaElementUserControl は MediaElement コントロールをカプセル化します。

XAML

<UserControl
    x:Class="MediaApp.MediaElementUserControl"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MediaApp"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    d:DesignHeight="300"
    d:DesignWidth="400">

    <Grid>
        <MediaElement AreTransportControlsEnabled="True" 
                      Source="Assets/UWPDesign.mp4"/>
    </Grid>
</UserControl>

Note

MediaElementUserControl のコードページには、生成されたコードのみが含まれているため、ここでは示しません。

IsTypePresent に基づいてコントロールを初期化する

実行時に、ApiInformation.IsTypePresent を呼び出して、MediaPlayerElement の有無を確認します。 MediaPlayerElement が存在する場合は MediaPlayerUserControl を読み込み、存在しない場合は MediaElementUserControl を読み込みます。

public MainPage()
{
    this.InitializeComponent();

    UserControl mediaControl;

    // Check for presence of type MediaPlayerElement.
    if (ApiInformation.IsTypePresent("Windows.UI.Xaml.Controls.MediaPlayerElement"))
    {
        mediaControl = new MediaPlayerUserControl();
    }
    else
    {
        mediaControl = new MediaElementUserControl();
    }

    // Add mediaControl to XAML visual tree (rootGrid is defined in XAML).
    rootGrid.Children.Add(mediaControl);
}

重要

このチェックでは mediaControl オブジェクトを MediaPlayerUserControl または MediaElementUserControl に設定するだけです。コード内の MediaPlayerElement API と MediaElement API のどちらを使うのかを判断する必要がある他の場所でこれらの条件付きチェックを実行する必要があります。チェックを一度実行してから結果をキャッシュし、キャッシュされた結果をアプリ全体で使う必要があります。

状態トリガーの例

拡張可能な状態トリガーでは、マークアップとコードを一緒に使って、コードでチェックする条件 (ここでは、特定の API が存在するかどうか) に基づいて表示状態の変更をトリガーできます。関係するオーバーヘッドと、表示状態のみへの制限があるため、一般的なアダプティブコードシナリオで状態トリガーを使うことはお勧めしません。

コントロール上のプロパティ値や列挙値の変更など、残りの UI に影響しない、異なる OS バージョン間での小さな UI の変更がある場合のみ、アダプティブコードに状態トリガーを使ってください。

例 1:新しいプロパティ

拡張可能な状態トリガーを設定する最初の手順は、StateTriggerBase クラスのサブクラスを作成して、API の有無に基づいてアクティブになるカスタムトリガーを作成することです。この例は、プロパティの有無が XAML に設定されている _isPresent 変数に一致する場合にアクティブ化されるトリガーを示しています。

class IsPropertyPresentTrigger : StateTriggerBase
{
    public string TypeName { get; set; }
    public string PropertyName { get; set; }

    private Boolean _isPresent;
    private bool? _isPropertyPresent = null;

    public Boolean IsPresent
    {
        get { return _isPresent; }
        set
        {
            _isPresent = value;
            if (_isPropertyPresent == null)
            {
                // Call into ApiInformation method to determine if property is present.
                _isPropertyPresent =
                ApiInformation.IsPropertyPresent(TypeName, PropertyName);
            }

            // If the property presence matches _isPresent then the trigger will be activated;
            SetActive(_isPresent == _isPropertyPresent);
        }
    }
}

次の手順は、XAML で表示状態トリガーを設定して、2 つの異なる表示状態が API の有無に基づいた結果になるようにします。

Windows 10 バージョン 1607 では、ユーザーがコントロールを操作するときにそのコントロールがフォーカスを取得するかどうかを判断する AllowFocusOnInteraction と呼ばれる新しいプロパティが FrameworkElement クラスに導入されています。これは、ユーザーがボタンをクリックしたときに、データ入力用のテキストボックスにフォーカスを保持する (タッチキーボードを表示したままにする) のに役立ちます。

この例のトリガーは、プロパティが存在するかどうかをチェックします。プロパティが存在する場合、Button の AllowFocusOnInteraction プロパティが false に設定されます。プロパティが存在しない場合は、Button はその元の状態を保持します。 TextBox は、コードの実行時にこのプロパティの影響をわかりやすくするために含まれています。

XAML

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <StackPanel>
        <TextBox Width="300" Height="36"/>
        <!-- Button to set the new property on. -->
        <Button x:Name="testButton" Content="Test" Margin="12"/>
    </StackPanel>

    <VisualStateManager.VisualStateGroups>
        <VisualStateGroup x:Name="propertyPresentStateGroup">
            <VisualState>
                <VisualState.StateTriggers>
                    <!--Trigger will activate if the AllowFocusOnInteraction property is present-->
                    <local:IsPropertyPresentTrigger 
                        TypeName="Windows.UI.Xaml.FrameworkElement" 
                        PropertyName="AllowFocusOnInteraction" IsPresent="True"/>
                </VisualState.StateTriggers>
                <VisualState.Setters>
                    <Setter Target="testButton.AllowFocusOnInteraction" 
                            Value="False"/>
                </VisualState.Setters>
            </VisualState>
        </VisualStateGroup>
    </VisualStateManager.VisualStateGroups>
</Grid>

例 2: 新しい列挙値

次の例は、値が存在するかどうかに基づいてさまざまな列挙値を設定する方法を示しています。カスタム状態トリガーを使って、前のチャットの例と同じ結果を実現します。この例では、デバイスが Windows 10 バージョン 1607 を実行している場合に、新しい ChatWithoutEmoji 入力スコープを使います。それ以外の場合、Chat 入力スコープが使われます。このトリガーを使う表示状態は、新しい列挙値の有無に基づいて入力スコープが選択される if-else スタイルで設定されます。

class IsEnumPresentTrigger : StateTriggerBase
{
    public string EnumTypeName { get; set; }
    public string EnumValueName { get; set; }

    private Boolean _isPresent;
    private bool? _isEnumValuePresent = null;

    public Boolean IsPresent
    {
        get { return _isPresent; }
        set
        {
            _isPresent = value;

            if (_isEnumValuePresent == null)
            {
                // Call into ApiInformation method to determine if value is present.
                _isEnumValuePresent =
                ApiInformation.IsEnumNamedValuePresent(EnumTypeName, EnumValueName);
            }

            // If the property presence matches _isPresent then the trigger will be activated;
            SetActive(_isPresent == _isEnumValuePresent);
        }
    }
}

XAML

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

    <TextBox x:Name="messageBox"
     AcceptsReturn="True" TextWrapping="Wrap"/>


    <VisualStateManager.VisualStateGroups>
        <VisualStateGroup x:Name="EnumPresentStates">
            <!--if-->
            <VisualState x:Name="isPresent">
                <VisualState.StateTriggers>
                    <local:IsEnumPresentTrigger 
                        EnumTypeName="Windows.UI.Xaml.Input.InputScopeNameValue" 
                        EnumValueName="ChatWithoutEmoji" IsPresent="True"/>
                </VisualState.StateTriggers>
                <VisualState.Setters>
                    <Setter Target="messageBox.InputScope" Value="ChatWithoutEmoji"/>
                </VisualState.Setters>
            </VisualState>
            <!--else-->
            <VisualState x:Name="isNotPresent">
                <VisualState.StateTriggers>
                    <local:IsEnumPresentTrigger 
                        EnumTypeName="Windows.UI.Xaml.Input.InputScopeNameValue" 
                        EnumValueName="ChatWithoutEmoji" IsPresent="False"/>
                </VisualState.StateTriggers>
                <VisualState.Setters>
                    <Setter Target="messageBox.InputScope" Value="Chat"/>
                </VisualState.Setters>
            </VisualState>
        </VisualStateGroup>
    </VisualStateManager.VisualStateGroups>
</Grid>

バージョンアダプティブコード

ランタイム API チェック

サポートされていないシナリオ

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

アダプティブコードの例

例 1:新しい列挙値

例 2: 新しいコントロール

状態トリガーの例

例 1:新しいプロパティ

例 2: 新しい列挙値

フィードバック

フィードバック

その他のリソース

バージョン アダプティブ コード

ランタイム API チェック

サポートされていないシナリオ

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

アダプティブ コードの例

例 1:新しい列挙値

例 2: 新しいコントロール

状態トリガーの例

例 1:新しいプロパティ

例 2: 新しい列挙値

関連記事

フィードバック

フィードバック

その他のリソース

バージョンアダプティブコード

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

アダプティブコードの例