WPF におけるパッケージの URI
Windows Presentation Foundation (WPF) において、uniform resource identifiers (URIs) は次のようなさまざまな用途でファイルを指定し、読み込むために使用されます。
アプリケーションの起動時に表示する user interface (UI) の指定。
イメージの読み込み。
ページへの移動。
実行可能ファイルではないデータ ファイルの読み込み。
また、URIs を使用して、次に示すようなさまざまな場所にあるファイルを指定し、読み込むことができます。
現在のアセンブリ。
参照アセンブリ。
アセンブリを基準とした場所。
アプリケーションの起点サイト。
こうした場所にある各種ファイルを指定して読み込むため、一貫性のある仕組みの提供を目的として、WPF ではパッケージの URI スキームを採用しています。 このトピックでは、このスキームの概要、さまざまなシナリオでのパッケージの URIs の作成方法、絶対および相対 URIs と URI の解決について説明した後、マークアップやコードでパッケージの URIs を使用する方法について説明します。
このトピックは、次のセクションで構成されています。
- パッケージの URI スキーム
- リソース ファイル パッケージの URI
- コンテンツ ファイルのパッケージの URI
- 起点サイトのパッケージの URI
- パッケージ ファイル
- 絶対パッケージの URI と相対パッケージの URI
- パッケージの URI の解決
- パッケージの URI を使用したプログラミング
- 関連トピック
パッケージの URI スキーム
パッケージの URI スキームは、Open Packaging Conventions (OPC) 仕様で使用されています。この仕様は、コンテンツの編成および特定について規定します。 このモデルの主な要素はパッケージとパーツです。パッケージは、1 つ以上の論理パーツの論理コンテナーです。 この概念を次の図に示します。
.png "パッケージとパーツのダイアグラム")
パーツの識別を目的として、OPC 仕様では、パッケージの URI スキームを定義するために、RFC 2396 (Uniform Resource Identifiers (URI): Generic Syntax) の拡張機能を利用しています。
URI で指定されるスキームは、そのプレフィックスで定義されます。http、ftp、file などがよく知られています。 パッケージの URI スキームは、スキームとして pack を使用し、証明機関とパスの 2 つのコンポーネントが含まれます。 パッケージの URI の書式は次のとおりです。
pack://authority/path
authority は、パーツが格納されているパッケージの種類を指定し、path は、パッケージ内のパーツの場所を指定します。
この概念を次の図に示します。
.png "パッケージ、権限、およびパスの間のリレーションシップ")
パッケージとパーツは、アプリケーションとアプリケーション データ ファイルに似ています。つまり、アプリケーション (パッケージ) には、次のような 1 つ以上のファイル (パーツ) を含めることができます。
ローカル アセンブリにコンパイルされるリソース ファイル。
参照アセンブリにコンパイルされるリソース ファイル。
参照元のアセンブリにコンパイルされるリソース ファイル。
コンテンツ ファイル。
起点サイト ファイル。
これらのファイルにアクセスするために、WPF は、application:/// と siteoforigin:/// という 2 つの証明機関をサポートします。 application:/// 証明機関は、リソース ファイルやコンテンツ ファイルなど、コンパイル時に既知のアプリケーション データ ファイルを示すために使用されます。 siteoforigin:/// 証明機関は、起点サイト ファイルの指定に使用されます。 各証明機関のスコープを、次の図に示します。
.png "Pack URI のダイアグラム")
.gif "メモ") メモ |
|---|
パッケージの URI の証明機関コンポーネントは、パッケージを指す埋め込みの URI で、RFC 2396 に準拠する必要があります。また、"/" 文字は "," 文字に置き換え、"%" や "?" などの予約文字はエスケープする必要があります。詳細については、OPC を参照してください。 |
以下のセクションでは、2 つの証明機関と、リソース ファイル、コンテンツ ファイル、および起点サイト ファイルの適切なパスとを組み合わせて使用して、パッケージの URIs を構築する方法について説明します。
リソース ファイル パッケージの URI
リソース ファイルは MSBuild Resource 項目として構成され、コンパイルされてアセンブリに変換されます。 WPF は、ローカル アセンブリに変換されたリソース ファイルの指定やローカル アセンブリから参照されるアセンブリに変換されたリソース ファイルの指定に使用できるパッケージの URIs の構築をサポートしています。
ローカル アセンブリ リソース ファイル
ローカル アセンブリにコンパイルされるリソース ファイルのパッケージ URI は、次の証明機関とパスを使用します。
証明機関 : application:///。
パス : ローカル アセンブリ プロジェクト フォルダーのルートを基準とするパスを含む、リソース ファイルの名前。
ローカル アセンブリのプロジェクト フォルダーのルートにある XAML リソース ファイルのパッケージの URI の例を次に示します。
pack://application:,,,/ResourceFile.xaml
ローカル アセンブリのプロジェクト フォルダーのサブフォルダーにある XAML リソース ファイルのパッケージの URI の例を次に示します。
pack://application:,,,/Subfolder/ResourceFile.xaml
参照アセンブリ リソース ファイル
参照アセンブリにコンパイルされるリソース ファイルのパッケージ URI は、次の証明機関とパスを使用します。
証明機関 : application:///。
パス : コンパイルされて参照アセンブリに変換されるリソース ファイルの名前。 パスは、次の書式に従う必要があります。
AssemblyShortName[;Version][;PublicKey];component/Path
AssemblyShortName : 参照アセンブリの短い名前。
;Version (省略可能): リソース ファイルを含む参照アセンブリのバージョン。 これは、同じ短い名前を持つ 2 つ以上の参照アセンブリを読み込む場合に使用されます。
;PublicKey (省略可能): 参照アセンブリの署名に使用された公開キー。 これは、同じ短い名前を持つ 2 つ以上の参照アセンブリを読み込む場合に使用されます。
;component: 参照アセンブリがローカル アセンブリから参照されることを指定します。
/Path: 参照アセンブリのプロジェクト フォルダーのルートを基準とするパスを含む、リソース ファイルの名前。
参照アセンブリのプロジェクト フォルダーのルートにある XAML リソース ファイルのパッケージの URI の例を次に示します。
pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml
参照アセンブリのプロジェクト フォルダーのサブフォルダーにある XAML リソース ファイルのパッケージの URI の例を次に示します。
pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml
バージョン固有の参照アセンブリのプロジェクト フォルダーのルート フォルダーにある XAML リソース ファイルのパッケージの URI の例を次に示します。
pack://application:,,,/ReferencedAssembly;v1.0.0.1;component/ResourceFile.xaml
参照アセンブリ リソース ファイルのパッケージの URI 構文は、application:/// 証明機関と組み合わせる場合のみ使用できます。 たとえば、WPF では次はサポートされません。
pack://siteoforigin:,,,/SomeAssembly;component/ResourceFile.xaml
コンテンツ ファイルのパッケージの URI
コンテンツ ファイルのパッケージ URI は、次の証明機関とパスを使用します。
証明機関 : application:///。
パス : アプリケーションのメインの実行可能アセンブリのファイル システムの場所を基準とするパスを含む、コンテンツ ファイルの名前。
実行可能アセンブリと同じフォルダーにある XAML コンテンツ ファイルのパッケージの URI の例を次に示します。
pack://application:,,,/ContentFile.xaml
アプリケーションの実行可能アセンブリを基準とするサブフォルダーにある XAML コンテンツ ファイルのパッケージの URI の例を次に示します。
pack://application:,,,/Subfolder/ContentFile.xaml
| メモ |
|---|
HTML コンテンツ ファイルは、移動先にはできません。URI スキームは、起点サイトにある HTML ファイルへの移動のみをサポートします。 |
起点サイトのパッケージの URI
起点サイト ファイルのパッケージ URI は、次の証明機関とパスを使用します。
証明機関 : siteoforigin:///。
パス : 実行可能アセンブリが起動される場所を基準とするパスを含む、起点サイト ファイルの名前。
実行可能アセンブリが起動される場所に格納されている、XAML 起点サイト ファイルのパッケージの URI の例を次に示します。
pack://siteoforigin:,,,/SiteOfOriginFile.xaml
アプリケーションの実行可能アセンブリが起動される場所を基準とするサブフォルダーに格納されている、XAML 起点サイト ファイルのパッケージの URI の例を次に示します。
pack://siteoforigin:,,,/Subfolder/SiteOfOriginFile.xaml
パッケージ ファイル
MSBuild Page 項目として構成されている XAML ファイルは、リソース ファイルと同じようにしてコンパイルされ、アセンブリに変換されます。 したがって、MSBuild Page 項目は、リソース ファイルのパッケージの URIs を使用して指定できます。
一般的に MSBuild Page 項目として構成される XAML ファイルの種類には、ルート要素として次のいずれかが含まれます。
絶対パッケージの URI と相対パッケージの URI
完全修飾パッケージの URI にはスキーム、証明機関、パスが含まれ、絶対パッケージの URI と見なされます。 開発者にとっての簡便さを考慮して、通常、XAML 要素では、パスだけを含む相対パッケージ URI で適切な属性を設定できます。
たとえば、ローカル アセンブリ内のリソース ファイルに対する次の絶対パッケージの URI を考えてみます。
pack://application:,,,/ResourceFile.xaml
このリソース ファイルを参照する相対パッケージの URI は、次のようになります。
/ResourceFile.xaml
| メモ |
|---|
起点サイト ファイルはアセンブリに関連付けられていないため、絶対パッケージの URIs を使用した参照のみ可能です。 |
既定では、相対パッケージの URI は、参照を含むマークアップまたはコードの位置を基準にしていると見なされます。 ただし、先頭にバックスラッシュを使用すると、相対パッケージ URI 参照はアプリケーションのルートに対して相対的であると見なされます。 たとえば、次のプロジェクト構造を考えます。
App.xaml
Page2.xaml
\SubFolder
+ Page1.xaml
+ Page2.xaml
Page1.xaml に Root\SubFolder\Page2.xaml を参照する URI が含まれている場合、参照で次の相対パッケージの URI を使用できます。
Page2.xaml
Page1.xaml に Root\Page2.xaml を参照する URI が含まれている場合、参照で次の相対パッケージの URI を使用できます。
/Page2.xaml
パッケージの URI の解決
パッケージの URIs の形式は、さまざまな種類のファイルのパッケージの URIs が同じに見えるようになっています。 たとえば、次の絶対パッケージの URI について検討してみます。
pack://application:,,,/ResourceOrContentFile.xaml
この絶対パッケージの URI は、ローカル アセンブリ内のリソース ファイルまたはコンテンツ ファイルを参照できます。 同じことは、次の相対 URI にも当てはまります。
/ResourceOrContentFile.xaml
パッケージの URI が参照しているファイルの種類を特定するために、WPF は、次のヒューリスティックを使用して、ローカル アセンブリ内のリソース ファイルとコンテンツ ファイルの URIs を解決します。
アセンブリ メタデータに、パッケージの URI に一致する AssemblyAssociatedContentFileAttribute 属性があるかどうかを調べます。
AssemblyAssociatedContentFileAttribute 属性が見つかった場合は、パッケージ URI のパスはコンテンツ ファイルを参照しています。
AssemblyAssociatedContentFileAttribute 属性が見つからない場合、コンパイルされてローカル アセンブリに変換された設定リソース ファイルを調べます。
パッケージ URI のパスに一致するリソース ファイルが見つかると、パッケージ URI のパスはリソース ファイルを参照しています。
リソースが見つからない場合、内部で作成された Uri は無効です。
URI 解決は、次を参照する URIs には適用されません。
参照アセンブリ内のコンテンツ ファイル : この種類のファイルは WPF でサポートされません。
参照アセンブリに埋め込まれたファイル : これらを指定する URIs は、参照アセンブリの名前と ;component サフィックスの両方が含まれているため、一意です。
起点サイト ファイル : これらを指定する URIs は、siteoforigin:/// 証明機関を含むパッケージの URIs で指定できる唯一の種類のファイルあるため、一意です。
パッケージの URI 解決によってもたらされる 1 つの単純化は、コードがリソース ファイルやコンテンツ ファイルの場所に依存しなくなることです。 たとえば、コンテンツ ファイルに再構成されたリソース ファイルがローカル アセンブリにある場合、そのリソースのパッケージの URI は変わらず、そのパッケージの URI を使用するコードも変わりません。
パッケージの URI を使用したプログラミング
多くの WPF クラスは、パッケージの URIs を使用して設定できる次のようなプロパティを実装します。
これらのプロパティは、マークアップとコードのどちらからも設定できます。 ここでは、両方の構造と共通シナリオについて説明します。
マークアップでのパッケージの URI の使用
マークアップでパッケージの URI を指定するには、パッケージの URI を使用する属性の要素を設定します。 次に例を示します。
<element attribute="pack://application:,,,/File.xaml" />
表 1 は、マークアップで指定できるさまざまな絶対パッケージの URIs を示しています。
表 1 : マークアップでの絶対パッケージの URI
ファイル |
絶対パッケージの URI |
|---|---|
リソース ファイル - ローカル アセンブリ |
"pack://application:,,,/ResourceFile.xaml" |
サブフォルダー内のリソース ファイル - ローカル アセンブリ |
"pack://application:,,,/Subfolder/ResourceFile.xaml" |
リソース ファイル - 参照アセンブリ |
"pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml" |
参照アセンブリのサブフォルダー内のリソース ファイル |
"pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml" |
バージョン管理された参照アセンブリ内のリソース ファイル |
"pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml" |
コンテンツ ファイル |
"pack://application:,,,/ContentFile.xaml" |
サブフォルダー内のコンテンツ ファイル |
"pack://application:,,,/Subfolder/ContentFile.xaml" |
起点サイト ファイル |
"pack://siteoforigin:,,,/SOOFile.xaml" |
サブフォルダー内の起点サイト ファイル |
"pack://siteoforigin:,,,/Subfolder/SOOFile.xaml" |
表 2 は、マークアップで指定できるさまざまな相対パッケージの URIs を示しています。
表 2 : マークアップでの相対パッケージの URI
ファイル |
相対パッケージの URI |
|---|---|
ローカル アセンブリ内のリソース ファイル |
"/ResourceFile.xaml" |
ローカル アセンブリのサブフォルダー内のリソース ファイル |
"/Subfolder/ResourceFile.xaml" |
参照アセンブリ内のリソース ファイル |
"/ReferencedAssembly;component/ResourceFile.xaml" |
参照アセンブリのサブフォルダー内のリソース ファイル |
"/ReferencedAssembly;component/Subfolder/ResourceFile.xaml" |
コンテンツ ファイル |
"/ContentFile.xaml" |
サブフォルダー内のコンテンツ ファイル |
"/Subfolder/ContentFile.xaml" |
コードでのパッケージの URI の使用
コードでパッケージの URI を指定するには、Uri クラスをインスタンス化し、パッケージの URI をパラメーターとしてコンストラクターに渡します。 このコード例を次に示します。
Uri uri = new Uri("pack://application:,,,/File.xaml");
既定では、Uri クラスは、パッケージの URIs を絶対と見なします。 そのため、Uri クラスのインスタンスが相対パッケージの URI を使用して作成されると、例外が発生します。
Uri uri = new Uri("/File.xaml");
しかし、Uri クラスのコンストラクターの Uri(String, UriKind) オーバーロードは、UriKind 型のパラメーターを受け取ります。これを使用すると、パッケージの URI が絶対または相対のどちらであるかを指定できます。
// Absolute URI (default)
Uri absoluteUri = new Uri("pack://application:,,,/File.xaml", UriKind.Absolute);
// Relative URI
Uri relativeUri = new Uri("/File.xaml", UriKind.Relative);
提供されたパッケージ URI が Absolute と Relative のどちらであるかわかっている場合は、それだけを指定します。 使用されているパッケージの URI の種類がわからない場合、たとえばユーザーがパッケージの URI を実行時に入力する場合は、代わりに RelativeOrAbsolute を使用します。
// Relative or Absolute URI provided by user via a text box
TextBox userProvidedUriTextBox = new TextBox();
Uri uri = new Uri(userProvidedUriTextBox.Text, UriKind.RelativeOrAbsolute);
表 3 は、System.Uri を使用してコードで指定できるさまざまな絶対パッケージの URIs を示しています。
表 3 : コードでの絶対パッケージの URI
ファイル |
絶対パッケージの URI |
|---|---|
リソース ファイル - ローカル アセンブリ |
Uri uri = new Uri("pack://application:,,,/ResourceFile.xaml", UriKind.Absolute); |
サブフォルダー内のリソース ファイル - ローカル アセンブリ |
Uri uri = new Uri("pack://application:,,,/Subfolder/ResourceFile.xaml", UriKind.Absolute); |
リソース ファイル - 参照アセンブリ |
Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Absolute); |
参照アセンブリのサブフォルダー内のリソース ファイル |
Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Absolute); |
バージョン管理された参照アセンブリ内のリソース ファイル |
Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml", UriKind.Absolute); |
コンテンツ ファイル |
Uri uri = new Uri("pack://application:,,,/ContentFile.xaml", UriKind.Absolute); |
サブフォルダー内のコンテンツ ファイル |
Uri uri = new Uri("pack://application:,,,/Subfolder/ContentFile.xaml", UriKind.Absolute); |
起点サイト ファイル |
Uri uri = new Uri("pack://siteoforigin:,,,/SOOFile.xaml", UriKind.Absolute); |
サブフォルダー内の起点サイト ファイル |
Uri uri = new Uri("pack://siteoforigin:,,,/Subfolder/SOOFile.xaml", UriKind.Absolute); |
表 4 は、System.Uri を使用してコードで指定できるさまざまな相対パッケージの URIs を示しています。
表 4 : コードでの相対パッケージの URI
ファイル |
相対パッケージの URI |
|---|---|
リソース ファイル - ローカル アセンブリ |
Uri uri = new Uri("/ResourceFile.xaml", UriKind.Relative); |
サブフォルダー内のリソース ファイル - ローカル アセンブリ |
Uri uri = new Uri("/Subfolder/ResourceFile.xaml", UriKind.Relative); |
リソース ファイル - 参照アセンブリ |
Uri uri = new Uri("/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Relative); |
サブフォルダー内のリソース ファイル - 参照アセンブリ |
Uri uri = new Uri("/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Relative); |
コンテンツ ファイル |
Uri uri = new Uri("/ContentFile.xaml", UriKind.Relative); |
サブフォルダー内のコンテンツ ファイル |
Uri uri = new Uri("/Subfolder/ContentFile.xaml", UriKind.Relative); |
パッケージの URI 関連の一般的なシナリオ
ここまで、リソース ファイル、コンテンツ ファイル、および起点サイト ファイルを指定するためにパッケージの URIs を構築する方法を説明してきました。 WPF では、こうした構造はさまざまな方法で使用されています。以下のセクションでは、いくつかの一般的な用途について説明します。
アプリケーションの起動時に表示する UI の指定
StartupUri は、WPF アプリケーションの起動時に表示する最初の UI を指定します。 スタンドアロン アプリケーションでは、次の例に示すように、UI としてウィンドウを使用できます。
<Application
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
StartupUri="MainWindow.xaml" />
スタンドアロン アプリケーションおよび XAML browser applications (XBAPs) では、次の例に示すように、初期 UI としてページを指定することもできます。
<Application
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
StartupUri="HomePage.xaml" />
アプリケーションがスタンドアロン アプリケーションであり、ページが StartupUri を使用して指定されている場合、WPF は NavigationWindow を開いてページをホストします。 XBAPs の場合、ページはホスト ブラウザーに表示されます。
ページへの移動
ページへの移動方法を次の例に示します。
<Page
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
WindowTitle="Page With Hyperlink"
WindowWidth="250"
WindowHeight="250">
...
<Hyperlink NavigateUri="UriOfPageToNavigateTo.xaml">
Navigate to Another Page
</Hyperlink>
...
</Page>
WPF で移動に使用できるさまざまな方法の詳細については、「ナビゲーションの概要」を参照してください。
ウィンドウ アイコンの指定
URI を使用してウィンドウのアイコンを指定する方法を次の例に示します。
<Window
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
x:Class="SDKSample.MainWindow"
Icon="WPFIcon1.ico">
</Window>
詳細については、「Icon」を参照してください。
イメージ ファイル、オーディオ ファイル、およびビデオ ファイルの読み込み
WPF を使用すると、アプリケーションでさまざまな種類のメディアを使用できます。次の例に示すように、それらはどれもパッケージの URIs を使用して指定し、読み込むことができます。
<MediaElement Stretch="Fill" LoadedBehavior="Play" Source="pack://siteoforigin:,,,/Media/bee.wmv" />
<MediaElement Stretch="Fill" LoadedBehavior="Play" Source="pack://siteoforigin:,,,/Media/ringin.wav" />
<Image Source="Images/Watermark.png" />
メディア コンテンツの操作方法の詳細については、「グラフィックスとマルチメディア」を参照してください。
起点サイトからのリソース ディクショナリの読み込み
リソース ディクショナリ (ResourceDictionary) は、アプリケーション テーマのサポートに使用できます。 テーマを作成および管理する 1 つの方法は、複数のテーマをリソース ディクショナリとして作成し、アプリケーションの起点サイトに配置することです。 これにより、アプリケーションを再コンパイルして再配置することなく、テーマを追加および更新できます。 これらのリソース ディクショナリは、次の例に示すように、パッケージの URIs を使用して指定し、読み込むことができます。
<Application
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
StartupUri="HomePage.xaml">
<Application.Resources>
<ResourceDictionary Source="pack://siteoforigin:,,,/PageTheme.xaml" />
</Application.Resources>
</Application>
WPF でのテーマの概要については、「スタイルとテンプレート」を参照してください。