ResourceDictionary と XAML リソースの参照

[アーティクル]
07/13/2023

XAML を使ってアプリの UI やリソースを定義できます。リソースとは、通常、複数回使うことが予定されたオブジェクトの定義です。後で XAML リソースを参照するために、名前のような働きをするリソースのキーを指定します。リソースは、アプリのどこからでも参照でき、アプリ内の任意の XAML ページからも参照できます。 Windows ランタイム XAML の ResourceDictionary 要素を使って、リソースを定義できます。リソースを定義すると、StaticResource マークアップ拡張または ThemeResource マークアップ拡張を使ってリソースを参照できます。

XAML リソースとして宣言することが多い XAML 要素としては、Style、ControlTemplate、アニメーションコンポーネント、および Brush サブクラスがあります。ここでは、ResourceDictionary とキーを持つリソースを定義する方法と、アプリまたはアプリパッケージの一部として定義する他のリソースと XAML リソースの関連について説明します。また、MergedDictionaries や ThemeDictionaries などのリソースディクショナリの高度な機能についても説明します。

前提条件

XAML マークアップに関するしっかりとした理解。 XAML の概要を読むことをお勧めします。

XAML リソースを定義して使う

XAML リソースは、マークアップから 2 回以上参照されるオブジェクトです。リソースは、ResourceDictionary で定義されます。通常は、別個のファイルで、または次のようにマークアップページの上部で定義されます。

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Page.Resources>
        <x:String x:Key="greeting">Hello world</x:String>
        <x:String x:Key="goodbye">Goodbye world</x:String>
    </Page.Resources>

    <TextBlock Text="{StaticResource greeting}" Foreground="Gray" VerticalAlignment="Center"/>
</Page>

この例では:

<Page.Resources>…</Page.Resources>: リソースディクショナリを定義します。
<x:String>: キー "greeting" を持つリソースを定義します。
{StaticResource greeting} - TextBlock の Text プロパティに割り当てられた、キー "greeting" を持つリソースを検索します。

注ResourceDictionary に関連する概念を、リソース ビルドアクション、リソース (.resw) ファイル、またはアプリパッケージを生成するコードプロジェクトの構築のコンテキストで説明されるその他の "リソース" と混同しないでください。

リソースを文字列にする必要はありません。スタイル、テンプレート、ブラシ、色など、任意の共有可能なオブジェクトにすることができます。ただし、コントロール、図形、および他の FrameworkElement は共有可能ではないため、再利用可能なリソースとして宣言することはできません。共有について詳しくは、このトピックの後方の「XAML リソースは共有できる必要がある」をご覧ください。

ここでは、ブラシと文字列の両方がリソースとして宣言されており、ページでコントロールにより使用されています。

<Page
    x:Class="SpiderMSDN.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Page.Resources>
        <SolidColorBrush x:Key="myFavoriteColor" Color="green"/>
        <x:String x:Key="greeting">Hello world</x:String>
    </Page.Resources>

    <TextBlock Foreground="{StaticResource myFavoriteColor}" Text="{StaticResource greeting}" VerticalAlignment="Top"/>
    <Button Foreground="{StaticResource myFavoriteColor}" Content="{StaticResource greeting}" VerticalAlignment="Center"/>
</Page>

すべてのリソースにはキーが必要です。通常、そのキーは x:Key="myString" を使って定義された文字列です。ただし、キーを指定する方法は他にもいくつかあります。

Style と ControlTemplate には TargetType が必要であり、x:Key が指定されていない場合は TargetType をキーとして使います。この場合、キーは文字列ではなく実際の Type オブジェクトです (以下の例をご覧ください)。
x:Key が指定されていない場合、TargetType を持つ DataTemplate リソースはキーとして TargetType を使います。この場合、キーは文字列ではなく実際の Type オブジェクトです
x:Name は x:Key の代わりに使うことができます。ただし、x:Name はリソースのコードビハインドフィールドも生成します。この結果、ページの読み込み時にそのフィールドを初期化する必要があるため、x:Name は x:Key よりも効率が低下します。

StaticResource マークアップ拡張は、文字列名 (x:Key または x:Name) を使ってのみリソースを取得できます。ただし、XAML フレームワークは、Style プロパティと ContentTemplate プロパティまたは ItemTemplate プロパティを設定していないコントロールに使用するスタイルテンプレートを決定するときに、暗黙的なスタイル & リソース (x:Key または x:Name ではなく TargetType を使用するもの) も検索します。

ここでは、Style に typeof(Button) の暗黙的なキーがあります。また、ページの下部にある Button は Style プロパティを指定しないため、キー typeof(Button) を持つスタイルを探します。

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Page.Resources>
        <Style TargetType="Button">
            <Setter Property="Background" Value="Red"/>
        </Style>
    </Page.Resources>
    <Grid>
       <!-- This button will have a red background. -->
       <Button Content="Button" Height="100" VerticalAlignment="Center" Width="100"/>
    </Grid>
</Page>

暗黙的なスタイルとそのしくみについて詳しくは、「コントロールのスタイル」と「コントロールテンプレート」をご覧ください。

コード内のリソースを検索する

その他のディクショナリなどのリソースディクショナリのメンバーにアクセスします。

警告

コード内でこのリソース検索を実行すると、Page.Resources ディクショナリ内のリソースだけが検索されます。 StaticResource マークアップ拡張とは異なり、最初のディクショナリでリソースが見つからない場合に、コードは Application.Resources ディクショナリにフォールバックしません。

この例では、ページのリソースディクショナリから redButtonStyle リソースを取得する方法を示します。

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Page.Resources>
        <Style TargetType="Button" x:Key="redButtonStyle">
            <Setter Property="Background" Value="red"/>
        </Style>
    </Page.Resources>
</Page>

    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
            Style redButtonStyle = (Style)this.Resources["redButtonStyle"];
        }
    }

    MainPage::MainPage()
    {
        InitializeComponent();
        Windows::UI::Xaml::Style style = Resources().TryLookup(winrt::box_value(L"redButtonStyle")).as<Windows::UI::Xaml::Style>();
    }

コードからアプリ全体のリソースを検索するには、ここに示すように Application.Current.Resources を使ってアプリのリソースディクショナリを取得します。

<Application
    x:Class="MSDNSample.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:SpiderMSDN">
    <Application.Resources>
        <Style TargetType="Button" x:Key="appButtonStyle">
            <Setter Property="Background" Value="red"/>
        </Style>
    </Application.Resources>

</Application>

    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
            Style appButtonStyle = (Style)Application.Current.Resources["appButtonStyle"];
        }
    }

    MainPage::MainPage()
    {
        InitializeComponent();
        Windows::UI::Xaml::Style style = Application::Current().Resources()
                                                               .TryLookup(winrt::box_value(L"appButtonStyle"))
                                                               .as<Windows::UI::Xaml::Style>();
    }

コードにアプリケーションリソースを追加することもできます。

この操作を実行する際に留意すべき点が 2 つあります。

まず、ページがリソースを使おうとする前にリソースを追加する必要があります。
次に、アプリのコンストラクターにリソースを追加することはできません。

これと同様に、Application.OnLaunched メソッドにリソースを追加した場合、両方の問題を回避することができます。

// App.xaml.cs
    
sealed partial class App : Application
{
    protected override void OnLaunched(LaunchActivatedEventArgs e)
    {
        Frame rootFrame = Window.Current.Content as Frame;
        if (rootFrame == null)
        {
            SolidColorBrush brush = new SolidColorBrush(Windows.UI.Color.FromArgb(255, 0, 255, 0)); // green
            this.Resources["brush"] = brush;
            // … Other code that VS generates for you …
        }
    }
}

// App.cpp

void App::OnLaunched(LaunchActivatedEventArgs const& e)
{
    Frame rootFrame{ nullptr };
    auto content = Window::Current().Content();
    if (content)
    {
        rootFrame = content.try_as<Frame>();
    }

    // Do not repeat app initialization when the Window already has content,
    // just ensure that the window is active
    if (rootFrame == nullptr)
    {
        Windows::UI::Xaml::Media::SolidColorBrush brush{ Windows::UI::ColorHelper::FromArgb(255, 0, 255, 0) };
        Resources().Insert(winrt::box_value(L"brush"), winrt::box_value(brush));
        // … Other code that VS generates for you …

各 FrameworkElement に ResourceDictionary を追加できる

FrameworkElement は、コントロールの継承元の基底クラスであり、Resources プロパティがあります。そのため、任意の FrameworkElement にローカルリソースディクショナリを追加できます。

ここでは、Page と Border の両方にリソースディクショナリがあり、どちらにも "greeting" というリソースがあります。 "textBlock2" という名前の TextBlock は Border 内にあるため、そのリソース検索はまず Border のリソースを検索した後、Page のリソース、次に Application のリソースの順に検索します。 TextBlock には、"Hola mundo" と表示されます。

コードからその要素のリソースにアクセスするには、その要素の Resources プロパティを使います。 XAML ではなくコード内の FrameworkElement のリソースにアクセスすると、親要素のディクショナリではなくそのディクショナリのみ検索されます。

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Page.Resources>
        <x:String x:Key="greeting">Hello world</x:String>
    </Page.Resources>
    
    <StackPanel>
        <!-- Displays "Hello world" -->
        <TextBlock x:Name="textBlock1" Text="{StaticResource greeting}"/>

        <Border x:Name="border">
            <Border.Resources>
                <x:String x:Key="greeting">Hola mundo</x:String>
            </Border.Resources>
            <!-- Displays "Hola mundo" -->
            <TextBlock x:Name="textBlock2" Text="{StaticResource greeting}"/>
        </Border>

        <!-- Displays "Hola mundo", set in code. -->
        <TextBlock x:Name="textBlock3"/>
    </StackPanel>
</Page>

    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();
            textBlock3.Text = (string)border.Resources["greeting"];
        }
    }

    MainPage::MainPage()
    {
        InitializeComponent();
        textBlock3().Text(unbox_value<hstring>(border().Resources().TryLookup(winrt::box_value(L"greeting"))));
    }

結合されたリソースディクショナリ

結合されたリソースディクショナリは、あるリソースディクショナリを別のディクショナリ (通常は別のファイルのディクショナリ) に結合します。

ヒント Microsoft Visual Studio でリソースディクショナリファイルを作成するには、[プロジェクト] メニューの [追加] > [新しい項目] > [リソースディクショナリ] オプションを使います。

ここでは、Dictionary1.xaml という別の XAML ファイルでリソースディクショナリを定義します。

<!-- Dictionary1.xaml -->
<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MSDNSample">

    <SolidColorBrush x:Key="brush" Color="Red"/>

</ResourceDictionary>

そのディクショナリを使うには、ページのディクショナリと結合します。

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Page.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="Dictionary1.xaml"/>
            </ResourceDictionary.MergedDictionaries>

            <x:String x:Key="greeting">Hello world</x:String>

        </ResourceDictionary>
    </Page.Resources>

    <TextBlock Foreground="{StaticResource brush}" Text="{StaticResource greeting}" VerticalAlignment="Center"/>
</Page>

この例の動作を次に示します。 <Page.Resources> で、<ResourceDictionary> を宣言します。リソースを <Page.Resources> に追加すると、XAML フレームワークによりリソースディクショナリが暗黙的に自動作成されますが、この場合に必要なのは通常のリソースディクショナリではなく、結合されたディクショナリを含むリソースディクショナリです。

そのため、<ResourceDictionary> を宣言し、<ResourceDictionary.MergedDictionaries> コレクションに内容を追加します。これらの各エントリは、<ResourceDictionary Source="Dictionary1.xaml"/> の形式を使います。複数のディクショナリを追加するには、最初のエントリの後に <ResourceDictionary Source="Dictionary2.xaml"/> エントリを追加するだけです。

<ResourceDictionary.MergedDictionaries>…</ResourceDictionary.MergedDictionaries> の後、オプションで追加のリソースをメインディクショナリに配置できます。結合されたディクショナリのリソースは、通常のディクショナリと同様に使います。上の例では、{StaticResource brush} は子ディクショナリと結合されたディクショナリ (Dictionary1.xaml) でリソースを検索しますが、{StaticResource greeting} はメインページディクショナリでそのリソースを参照します。

リソース検索シーケンスでは、MergedDictionaries ディクショナリはその ResourceDictionary のキーを持つその他すべてのリソースがチェックされた後にのみチェックされます。そのレベルが検索され、結合されたディクショナリに到達すると、MergedDictionaries 内の各項目がチェックされます。結合されたディクショナリが複数存在する場合、これらのディクショナリは MergedDictionaries プロパティで宣言された順序と反対の順序で確認されます。次の例では、Dictionary2.xaml と Dictionary1.xaml の両方が同じキーを宣言した場合、Dictionary2.xaml のキーが最初に使われます。これが MergedDictionaries セット内の最後のキーであるためです。

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Page.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="Dictionary1.xaml"/>
                <ResourceDictionary Source="Dictionary2.xaml"/>
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Page.Resources>

    <TextBlock Foreground="{StaticResource brush}" Text="greetings!" VerticalAlignment="Center"/>
</Page>

いずれかの ResourceDictionary のスコープ内で、ディクショナリのキーの一意性がチェックされます。ただし、そのスコープは異なる MergedDictionaries ファイル内の異なる項目間に拡張されません。

検索シーケンスと、一意のキーが結合されたディクショナリスコープを越えては適用されないことを組み合わせて使って、ResourceDictionary リソースのフォールバック値の順序を作成できます。たとえば、アプリの状態とユーザー設定データに同期されるリソースディクショナリを使って、シーケンス内で最後に結合されたリソースディクショナリに特定のブラシ色のユーザー設定を保存できます。ただし、ユーザー設定がまだ存在しない場合は、最初の MergedDictionaries ファイルで ResourceDictionary リソースに同じキー文字列を定義し、それをフォールバック値として使うことができます。プライマリリソースディクショナリで提供する値は、常に結合されたディクショナリがチェックされる前にチェックされるため、フォールバック手法を使う場合は、プライマリリソースディクショナリにそのリソースを定義しないでください。

テーマリソースとテーマディクショナリ

ThemeResource は StaticResource と似ていますが、テーマが変更されるとリソース検索が再評価されます。

この例では、TextBlock の前景色を現在のテーマの値に設定します。

<TextBlock Text="hello world" Foreground="{ThemeResource FocusVisualWhiteStrokeThemeBrush}" VerticalAlignment="Center"/>

テーマディクショナリは、ユーザーが自分のデバイスで現在使っているテーマに合わせて変化するリソースを保持する、特殊な種類の結合されたディクショナリです。たとえば、"light" テーマでは白いブラシが使われ、"dark" テーマでは暗い色のブラシが使われることがあります。ブラシによって解決先のリソースが変わりますが、ブラシをリソースとして使うコントロールの構成を同じにすることができます。独自のテンプレートとスタイルでテーマの切り替え動作を再現するには、MergedDictionaries をプロパティとして使って項目をメインディクショナリに結合する代わりに、ThemeDictionaries プロパティを使います。

ここで、ThemeDictionaries 内の各 ResourceDictionary 要素には x:Key 値が必要です。その値は、関連するテーマに名前を付ける文字列 (たとえば、"Default"、"Light"、"HighContrast") です。通常、Dictionary1 と Dictionary2 は名前が同じだが値が異なるリソースを定義します。

ここでは、淡色テーマに赤色のテキストを使い、濃色テーマに青色のテキストを使います。

<!-- Dictionary1.xaml -->
<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MSDNSample">

    <SolidColorBrush x:Key="brush" Color="Red"/>

</ResourceDictionary>

<!-- Dictionary2.xaml -->
<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MSDNSample">

    <SolidColorBrush x:Key="brush" Color="blue"/>

</ResourceDictionary>

この例では、TextBlock の前景色を現在のテーマの値に設定します。

<Page
    x:Class="MSDNSample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Page.Resources>
        <ResourceDictionary>
            <ResourceDictionary.ThemeDictionaries>
                <ResourceDictionary Source="Dictionary1.xaml" x:Key="Light"/>
                <ResourceDictionary Source="Dictionary2.xaml" x:Key="Dark"/>
            </ResourceDictionary.ThemeDictionaries>
        </ResourceDictionary>
    </Page.Resources>
    <TextBlock Foreground="{StaticResource brush}" Text="hello world" VerticalAlignment="Center"/>
</Page>

テーマディクショナリの場合、ThemeResource マークアップ拡張が参照のために使われ、システムによってテーマの変更が検出されるたびに、リソース検索に使われるアクティブなディクショナリは動的に変更されます。システムによって実行される検索の動作は、アクティブなテーマから特定のテーマディクショナリの x:Key へのマッピングに基づきます。

既定の XAML デザインリソースでテーマディクショナリが構築される方法を調べることが役立つ場合があります。これは、Windows ランタイムでそのコントロール用に既定で使われるテンプレートと似ています。テキストエディターか IDE を使用して、\(Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP\<SDK version>\Generic の XAML ファイルを開きます。テーマディクショナリが generic.xaml に最初に定義される方法と、各テーマディクショナリが同じキーを定義する方法に注意してください。このような各キーは、テーマディクショナリの外部にあり後で XAML で定義されるさまざまなキー付き要素の構成要素によって参照されます。デザイン用に別の themeresources.xaml というファイルもあり、これには既定のコントロールテンプレートではなく、テーマリソースと追加のテンプレートだけが含まれています。このテーマ領域は、generic.xaml に記載されているものの複製です。

XAML デザインツールを使ってスタイルとテンプレートのコピーを編集する際、デザインツールは、XAML デザインリソースディクショナリからセクションを抽出し、アプリとプロジェクトの一部である XAML ディクショナリ要素のローカルコピーとして配置します。

詳しい情報や、アプリで利用できるテーマ固有のリソースとシステムリソースの一覧については、「XAML テーマリソース」をご覧ください。

XAML リソース参照の検索の動作

検索の動作とは、XAML リソースシステムが XAML リソースを見つける方法を指します。検索は、キーがアプリの XAML 内のどこかから XAML リソースの参照として参照されるときに行われます。最初に、リソースシステムがスコープに基づいてリソースの存在をチェックする動作は予測可能です。リソースが最初のスコープで見つからない場合は、スコープが広がります。検索の動作は、XAML リソースがアプリまたはシステムで定義されている可能性のある場所とスコープで続けられます。すべての可能なリソース検索の試みが失敗すると、多くの場合、エラーが発生します。これらのエラーは通常、開発プロセス中に解消できます。

XAML リソース参照の検索の動作は、実際に使用が適用されるオブジェクトとその固有の Resources プロパティから開始します。 ResourceDictionary が存在する場合は、その ResourceDictionary で、要求されたキーを持つ項目が確認されます。通常はリソースを同じオブジェクトで定義して参照することはないため、最初のレベルの検索に意味があることはめったにありません。実際に、通常、Resources プロパティはここに存在しません。 XAML リソース参照は、XAML 内のほぼ任意の位置から作成できます。FrameworkElement サブクラスのプロパティには限定されません。

検索シーケンスでは、続いてアプリのランタイムオブジェクトツリーで次の親オブジェクトが確認されます。 FrameworkElement.Resources が存在し、ResourceDictionary を保持する場合、指定したキー文字列を持つディクショナリ項目が要求されます。リソースが見つかった場合は、検索シーケンスが停止し、参照された位置にオブジェクトが提供されます。それ以外の場合、検索動作はオブジェクトツリーのルートに向かって次の親レベルに進みます。検索は、XAML のルート要素に到達し、可能性のある即時リソースの場所がすべて検索されるまで、上方向へ再帰的に継続されます。

注意

このリソース参照動作を利用し、XAML マークアップスタイルの規則として、ページのルートレベルですべての即時リソースを定義するのが一般的な方法です。

要求されたリソースが即時リソースに見つからない場合、次の検索手順では Application.Resources プロパティが確認されます。 Application.Resources は、アプリのナビゲーション構造で複数のページによって参照されるアプリ固有のリソースを挿入するのに最適な場所です。

重要

ResourceDictionary にリソースが追加される順序は、それらが適用される順序に影響します。 XamlControlsResources ディクショナリによって多くの既定リソースキーがオーバーライドされるため、アプリ内の他のカスタムスタイルやリソースがオーバーライドされないように、まずこのディクショナリを Application.Resources に追加する必要があります。

制御テンプレートは、参照の検索に別の場所 (テーマディクショナリ) を使うこともできます。テーマディクショナリは、ResourceDictionary 要素をルートとして持つ単一の XAML ファイルです。テーマディクショナリは、Application.Resources からの結合されたディクショナリである場合があります。テーマディクショナリは、テンプレート化されたカスタムコントロールのコントロール固有のテーマディクショナリの場合もあります。

最後に、プラットフォームリソースに対するリソース検索があります。プラットフォームリソースには、システム UI テーマごとに定義されたコントロールテンプレートが含まれ、これは Windows ランタイムアプリで UI に使うすべてのコントロールの既定の外観を定義します。また、プラットフォームリソースには、システム全体の外観とテーマに関連する名前付きリソースのセットも含まれます。これらのリソースは技術的には MergedDictionaries 項目であるため、アプリの読み込み後に XAML またはコードからの検索で使うことができます。たとえば、システムテーマリソースには、アプリのテキストの色とシステムウィンドウのテキストの色 (この色はオペレーティングシステムとユーザー設定に基づく) を一致させるための Color 定義を提供する "SystemColorWindowTextColor" というリソースが含まれています。このスタイルはアプリの他の XAML スタイルで参照することができます。また、コードでリソース検索値を取得する (そしてこの例では Color にキャストする) こともできます。

詳しい情報や、XAML を使う Windows アプリで利用できるテーマ固有のリソースとシステムリソースの一覧については、「XAML テーマリソース」をご覧ください。

要求されたキーがこれらのいずれの場所にも見つからない場合は、XAML 解析エラーまたは例外が発生します。状況によっては、XAML 解析例外は、XAML マークアップコンパイル動作または XAML デザイン環境では検出されないランタイム例外の場合があります。

各リソースが異なるレベルで定義されている限り、リソースディクショナリの多層検索動作により、それぞれがキーと同じ文字列値を持つ複数のリソース項目を意図的に定義できます。つまり、キーは特定の ResourceDictionary 内で一意である必要がありますが、一意性の要件は検索の動作シーケンス全体には拡張されません。検索中は、最初に正常に取得されたこのオブジェクトのみが XAML リソースの参照に使われ、検索が停止します。アプリの XAML のさまざまな場所で同じ XAML リソースをキーを使って要求するためにこの動作を利用できますが、返されるリソースは XAML リソースの参照元のスコープと、その特定の検索がどのように動作するかによって異なります。

ResourceDictionary 内での前方参照

特定のリソースディクショナリ内の XAML リソース参照では、キーで既に定義されたリソースを参照する必要があり、そのリソースは辞書的にソース参照より前に出現する必要があります。前方参照は、XAML リソース参照によって解決できません。そのため、XAML リソース参照を別のリソースから使う場合は、他のリソースで使われるリソースがリソースディクショナリの先頭で定義されるように、リソースディクショナリ構造をデザインする必要があります。

アプリレベルで定義されたリソースは、即時リソースを参照できません。アプリリソースは実際には最初に (アプリが最初に起動し、ナビゲーションページコンテンツが読み込まれる前に) 処理されるため、これは前方参照の試行と同等です。ただし、任意の即時リソースでアプリリソースを参照でき、この手法が前方参照の状況の回避に役立つ場合があります。

XAML リソースは共有できる必要がある

オブジェクトが ResourceDictionary に存在するためには、そのオブジェクトが共有可能である必要があります。

共有できることが必要な理由は、アプリのオブジェクトツリーが実行時に構築されて使われるときに、オブジェクトはツリー内の複数の位置に存在できないためです。内部では、各 XAML リソースが要求されたときに、アプリのオブジェクトグラフで使うリソース値のコピーをリソースシステムが作成します。

一般に、ResourceDictionary と Windows ランタイム XAML では、共有の目的で次のオブジェクトがサポートされます。

スタイルとテンプレート (FrameworkTemplate から派生したクラスと Style)
ブラシと色 (Brush から派生したクラスと、Color の値)
Storyboard などのアニメーション型
変換 (GeneralTransform から派生したクラス)
Matrix および Matrix3D
Point 値
Thickness や CornerRadius など、その他の特定の UI 関連構造。
XAML 固有のデータ型

所定の実装パターンに従えば、カスタム型を共有可能なリソースとして使うこともできます。こうしたクラスは、バッキングコード (または含めるランタイムコンポーネント) で定義し、XAML でリソースとしてインスタンス化します。たとえば、オブジェクトデータソースや、データバインディングの IValueConverter 実装などです。

カスタム型には既定のコンストラクターが必要です。XAML パーサーは、そのコンストラクターを使ってクラスをインスタンス化するからです。リソースとして使われるカスタム型は、継承により UIElement クラスを持つことはできません。UIElement は共有できないためです (ランタイムアプリのオブジェクトグラフの特定の場所に存在する 1 つの UI 要素を表すためにのみ使われます)。

UserControl の使用のスコープ

UserControl 要素には、定義のスコープと使用のスコープという固有の概念があるため、リソース検索動作について特殊な状況があります。定義のスコープから XAML リソースを参照する UserControl は、固有の定義スコープ検索シーケンス内でそのリソースの検索をサポートできる必要があります。つまり、アプリリソースにはアクセスできません。 UserControl の使用のスコープからは、リソース参照は (読み込まれたオブジェクトツリー内のオブジェクトから行われる他のリソース参照と同様に) その使用ページのルートに向かう検索シーケンス内にあるものとして扱われ、アプリリソースにアクセスできます。

ResourceDictionary と XamlReader.Load

ResourceDictionary は、ルートとして、または XamlReader.Load メソッドの XAML 入力の一部として使うことができます。そのようなすべての参照が、読み込むために送信された XAML 内で完全に自己完結している場合、その XAML に XAML リソース参照を含めることもできます。 XamlReader.Load は、他の ResourceDictionary オブジェクトを (Application.Resources さえも) 認識しないコンテキストで XAML を解析します。また、XamlReader.Load に送信された XAML 内から {ThemeResource} を使わないでください。

コードからの ResourceDictionary の使用

ResourceDictionary のシナリオのほとんどが、XAML のみで処理されます。 UI 定義ファイルの XAML ノードセットまたは XAML ファイルとして ResourceDictionary コンテナーとリソースを宣言します。次に、XAML リソース参照を使って、XAML の他の部分からリソースを要求します。それでも、アプリの実行中にコードを実行して ResourceDictionary の内容を調整するというシナリオ、または、少なくとも ResourceDictionary の内容を照会して、リソースが定義済みかどうか確認するというシナリオもあります。これらのコードは ResourceDictionary インスタンスで呼び出されるため、最初に FrameworkElement.Resources を取得することでオブジェクトツリー内のどこかにある即時 ResourceDictionary を取得するか、Application.Current.Resources を取得する必要があります。

C# または Microsoft Visual Basic コードでは、インデクサー (Item) を使って所定の ResourceDictionary 内のリソースを参照できます。 ResourceDictionary は、文字列キーを持つディクショナリであるため、インデクサーは整数インデックスではなく文字列キーを使います。 Visual C++ コンポーネント拡張機能 (C++/CX) コードでは、Lookup を使います。

コードを使って ResourceDictionary を調査または変更するときは、Lookup や Item などの API の動作で、即時リソースからアプリリソースまで走査することはありません。XAML ページを読み込むときにのみ実行される XAML パーサーの動作とは異なります。実行時、キーのスコープはその時点で使っている ResourceDictionary インスタンスに対して自己完結しています。ただし、そのスコープは MergedDictionaries まで広がりません。

また、ResourceDictionary に存在しないキーを要求した場合、エラーにならないことがあります。単純に戻り値に null が返されます。ただし、返された null を値として使おうとすると、エラーになることがあります。エラーの原因として考えられるのは、ResourceDictionary の呼び出しではなく、プロパティの setter です。エラーにならないのは、プロパティが有効な値として null を受け取る場合だけです。この動作は、XAML 解析時の XAML 検索の動作とは対照的です。解析時に XAML から渡されたキーを解決できない場合、プロパティが null を受け付ける場合でも XAML 解析エラーが発生します。

結合されたリソースディクショナリは、実行時に結合されたディクショナリを参照するプライマリリソースディクショナリのインデックススコープに含まれます。つまり、プライマリディクショナリの Item または Lookup を使って、結合されたディクショナリに実際に定義されているオブジェクトを検索できます。この場合、検索の動作は解析時の XAML 検索の動作に似ています。結合されたディクショナリに同じキーを持つオブジェクトが複数ある場合は、最後に追加されたディクショナリのオブジェクトが返されます。

Add (C# または Visual Basic) または Insert (C++/CX) を呼び出すことで、既にある ResourceDictionary に項目を追加できます。即時リソースまたはアプリリソースに項目を追加できます。これらの API 呼び出しはどちらもキーを必要とします。これにより、ResourceDictionary の各項目にキーが必要という要件が満たされます。ただし、実行時に ResourceDictionary に追加した項目は、XAML リソース参照に関係しません。 XAML リソース参照に必要な検索は、アプリの読み込み時にその XAML が最初に解析されるとき (またはテーマの変更が検出されたとき) に実行されます。実行時にコレクションに追加されるリソースはその時点では使用できず、ResourceDictionary を変更しても、そこから取得済みのリソースは無効にはなりません。そのリソースの値を変更した場合でも同じです。

実行時に ResourceDictionary から項目を削除したり、一部またはすべての項目のコピーを作るなどの操作も実行できます。 ResourceDictionary に対して一覧表示されるメンバーは、利用できる API を示します。 ResourceDictionary には基になるコレクションインターフェイスをサポートするプロジェクションされた API があるため、API オプションは、C# または Visual Basic と C++/CX のどちらを使っているかによって異なります。

ResourceDictionary とローカライズ

最初に XAML ResourceDictionary には、ローカライズが必要な文字列が含まれていることがあります。その場合は、これらの文字列を ResourceDictionary にではなくプロジェクトリソースとして保存します。 XAML から文字列を取り出し、所有する要素に x:Uid ディレクティブ値を与えます。次に、リソースファイルにリソースを定義します。 XUIDValue.PropertyName の形式のリソース名と、ローカライズが必要な文字列のリソース値を提供します。

カスタムリソース検索

高度なシナリオとして、このトピックで説明した XAML リソース参照の検索の動作とは異なる動作を持つクラスを実装できます。そのためには、CustomXamlResourceLoader クラスを実装します。すると、StaticResource または ThemeResource を使う代わりにリソース参照に CustomResource markup extension を使って、この動作にアクセスできるようになります。ほとんどのアプリにこれを必要とするシナリオはありません。詳しくは、「CustomXamlResourceLoader」をご覧ください。

ResourceDictionary と XAML リソースの参照

前提条件

XAML リソースを定義して使う

コード内のリソースを検索する

各 FrameworkElement に ResourceDictionary を追加できる

結合されたリソースディクショナリ

テーマリソースとテーマディクショナリ

XAML リソース参照の検索の動作

ResourceDictionary 内での前方参照

XAML リソースは共有できる必要がある

UserControl の使用のスコープ

ResourceDictionary と XamlReader.Load

コードからの ResourceDictionary の使用

ResourceDictionary とローカライズ

カスタムリソース検索

その他のリソース

その他のリソース

ResourceDictionary と XAML リソースの参照

前提条件

XAML リソースを定義して使う

コード内のリソースを検索する

各 FrameworkElement に ResourceDictionary を追加できる

結合されたリソース ディクショナリ

テーマ リソースとテーマ ディクショナリ

XAML リソース参照の検索の動作

ResourceDictionary 内での前方参照

XAML リソースは共有できる必要がある

UserControl の使用のスコープ

ResourceDictionary と XamlReader.Load

コードからの ResourceDictionary の使用

ResourceDictionary とローカライズ

カスタム リソース検索

関連トピック

その他のリソース

その他のリソース

結合されたリソースディクショナリ

テーマリソースとテーマディクショナリ

カスタムリソース検索