リソース管理システムResource Management System

リソース管理システムには、ビルド時と実行時の両方の機能があります。The Resource Management System has both build-time and run-time features. ビルド時に、システムは、アプリとしてパッケージ化されているリソースのさまざまなバリエーションすべてのインデックスを作成します。At build time, the system creates an index of all the different variants of the resources that are packaged up with your app. このインデックスがパッケージ リソース インデックス (PRI) であり、アプリのパッケージにも含まれています。This index is the Package Resource Index, or PRI, and it's also included in your app's package. 実行時に、システムは、有効になっているユーザーやコンピューターの設定を検出し、PRI でその情報を参照して、それらの設定に最適なリソースを自動的に読み込みます。At run-time, the system detects the user and machine settings that are in effect, consults the information in the PRI, and automatically loads the resources that are the best match for those settings.

パッケージ リソース インデックス (PRI) ファイルPackage Resource Index (PRI) file

すべてのアプリ パッケージには、アプリ内のリソースのバイナリ インデックスが格納されている必要があります。Every app package should contain a binary index of the resources in the app. このインデックスはビルド時に作成され、1 つまたは複数のパッケージ リソース インデックス (PRI) ファイルに含まれています。This index is created at build time and it is contained in one or more Package Resource Index (PRI) files.

  • PRI ファイルには、実際の文字列リソースと、パッケージ内のさまざまなファイルを参照するファイル パスのインデックス付きセットが格納されます。A PRI file contains actual string resources, and an indexed set of file paths that refer to various files in the package.
  • パッケージには、通常、言語ごとに 1 つの、resources.pri という名前の PRI ファイルが含まれます。A package typically contains a single PRI file per language, named resources.pri.
  • 各パッケージのルートにある resources.pri ファイルは、ResourceManager がインスタンス化されたときに自動的に読み込まれます。The resources.pri file at the root of each package is automatically loaded when the ResourceManager is instantiated.
  • PRI ファイルを作成したりダンプしたりするには、MakePRI.exe というツールを使います。PRI files can be created and dumped with the tool MakePRI.exe.
  • 既に Visual Studio のコンパイル ワークフローに統合されているため、一般的なアプリの開発では、MakePRI.exe は必要ありません。For typical app development you won't need MakePRI.exe because it's already integrated into the Visual Studio compile workflow. また、Visual Studio は専用の UI で PRI ファイルの編集をサポートしています。And Visual Studio supports editing PRI files in a dedicated UI. ただし、ローカライズ担当者やローカライズ担当者が使うツールでは、MakePRI.exe が必要になる場合があります。However, your localizers and the tools they use might rely upon MakePRI.exe.
  • 各 PRI ファイルは、リソース マップと呼ばれる、リソースの名前付きコレクションを含みます。Each PRI file contains a named collection of resources, referred to as a resource map. パッケージの PRI ファイルが読み込まれたときに、リソース マップ名がパッケージ識別名と一致するかが確認されます。When a PRI file from a package is loaded, the resource map name is verified to match the package identity name.
  • PRI ファイルにはデータのみが格納され、移植可能な実行可能ファイル (PE) 形式は使用されません。PRI files contain only data, so they don't use the portable executable (PE) format. PRI ファイルは、Windows 向けのリソース形式としてデータ専用に設計されています。They are specifically designed to be data-only as the resource format for Windows. PRI ファイルは、Win32 アプリ モデルの DLL に含まれていたリソースに代わるものです。They replace resources contained within DLLs in the Win32 app model.
  • PRI ファイルのサイズ制限は、64 キロバイトです。The size limit on a PRI file is 64 kilobytes.

アプリ リソースへの UWP API のアクセスUWP API access to app resources

基本機能 (ResourceLoader)Basic functionality (ResourceLoader)

プログラムによってアプリ リソースにアクセスする最も簡単な方法は、Windows.ApplicationModel.Resources 名前空間と ResourceLoader クラスを使う方法です。The simplest way to access your app resources programmatically is by using the Windows.ApplicationModel.Resources namespace and the ResourceLoader class. ResourceLoader を使うと、一連のリソース ファイル、参照ライブラリ、または他のパッケージの文字列リソースへの基本的なアクセスが可能になります。ResourceLoader provides you basic access to string resources from the set of resource files, referenced libraries, or other packages.

高度な機能 (ResourceManager)Advanced functionality (ResourceManager)

Windows.ApplicationModel.Resources.Core 名前空間の ResourceManager クラスは、リソースに関する追加情報 (列挙、検査など) を提供します。The ResourceManager class (in the Windows.ApplicationModel.Resources.Core namespace) provides additional info about resources, such as enumeration and inspection. このクラスは、ResourceLoader クラスが提供する情報よりも多くの情報を提供します。This goes beyond what the ResourceLoader class provides.

NamedResource オブジェクトは、複数の言語またはその他の修飾されたバリアントを持つ個別の論理リソースです。A NamedResource object represents an individual logical resource with multiple language or other qualified variants. Header1 などの文字列リソース識別子や、logo.jpg などのリソース ファイル名を持つ、アセットやリソースの論理ビューを記述します。It describes the logical view of the asset or resource, with a string resource identifier such as Header1, or a resource file name such as logo.jpg.

ResourceCandidate オブジェクトは、英語向けの文字列 "Hello World" や scale-100 解像度に固有の修飾子付きのイメージ リソースである "logo.scale-100.jpg" など、単一の具象リソース値と修飾子の組み合わせです。A ResourceCandidate object represents a single concrete resource value and its qualifiers, such as the string "Hello World" for English, or "logo.scale-100.jpg" as a qualified image resource that's specific to the scale-100 resolution.

アプリで使うことができるリソースは、ResourceMap オブジェクトを使ってアクセスできる階層コレクションに格納されます。Resources available to an app are stored in hierarchical collections, which you can access with a ResourceMap object. ResourceManager クラスを使うと、アプリで使われる各種のトップレベルの ResourceMap インスタンスにアクセスできます。これらのインスタンスは、アプリのさまざまなパッケージに対応しています。The ResourceManager class provides access to the various top-level ResourceMap instances used by the app, which correspond to the various packages for the app. MainResourceMap の値は、参照されているフレームワーク パッケージではなく現在のアプリ パッケージのリソース マップに対応しています。The MainResourceMap value corresponds to the resource map for the current app package, and it excludes any referenced framework packages. それぞれの ResourceMap には、パッケージのマニフェストに指定されたパッケージ名に基づく名前が付けられます。Each ResourceMap is named for the package name that is specified in the package's manifest. ResourceMap には、NamedResource オブジェクトが格納されているサブツリー (「ResourceMap.GetSubtree」をご覧ください) が含まれています。Within a ResourceMap are subtrees (see ResourceMap.GetSubtree), which further contain NamedResource objects. 通常、サブツリーは、リソースが含まれるリソース ファイルに対応します。The subtrees typically correspond to the resource files that contains the resource. 詳しくは、「UI とアプリ パッケージ マニフェスト内の文字列をローカライズする表示倍率、テーマ、ハイ コントラスト、その他の設定に合わせた画像とアセットの読み込み」をご覧ください。For more info see Localize strings in your UI and app package manifest and Load images and assets tailored for scale, theme, high contrast, and others.

次に例を示します。Here's an example.

// using Windows.ApplicationModel.Resources.Core;
ResourceMap resourceMap =  ResourceManager.Current.MainResourceMap.GetSubtree("Resources");
ResourceContext resourceContext = ResourceContext.GetForCurrentView()
var str = resourceMap.GetValue("String1", resourceContext).ValueAsString;

リソース識別子は、URI (Uniform Resource Identifier) セマンティクスに応じて URI フラグメントとして処理されます。Note The resource identifier is treated as a Uniform Resource Identifier (URI) fragment, subject to URI semantics. たとえば、GetValue("Caption%20")GetValue("Caption ") として処理されます。For example, GetValue("Caption%20") is treated as GetValue("Caption "). リソース識別子で "?" や "#" を使うとリソース パスの評価がそこで中断されるので、使わないでください。Do not use "?" or "#" in resource identifiers, because they terminate the resource path evaluation. たとえば、"MyResource?3" は "MyResource" として扱われます。For example, "MyResource?3" is treated as "MyResource".

ResourceManager は、アプリの文字列リソースへのアクセスをサポートするだけでなく、さまざまなファイル リソースを列挙し検査する機能も保持します。The ResourceManager not only supports access to an app's string resources, it also maintains the ability to enumerate and inspect the various file resources as well. ファイルとその他のリソース (ファイル内から提供されるリソース) との衝突を回避するために、すべてのインデックス付きファイル パスは、予約済みの "Files" ResourceMap サブツリーに配置されます。In order to avoid collisions between files and other resources that originate from within a file, indexed file paths all reside within a reserved "Files" ResourceMap subtree. たとえば、ファイル \Images\logo.png は、リソース名 Files/images/logo.png に対応します。For example, the file \Images\logo.png corresponds to the resource name Files/images/logo.png.

StorageFile API は、リソースとしてのファイルへの参照を透過的に処理するため、一般的な用法のシナリオに適しています。The StorageFile APIs transparently handle references to files as resources, and are appropriate for typical usage scenarios. ResourceManager は、現在のコンテキストをオーバーライドする必要がある場合など、高度なシナリオについてのみ使用してください。The ResourceManager should only be used for advanced scenarios, such when you want to override the current context.

ResourceContextResourceContext

リソース候補は、リソース修飾子の値 (言語、スケール、コントラストなど) のコレクションである特定の ResourceContext に基づいて選ばれます。Resource candidates are chosen based on a particular ResourceContext, which is a collection of resource qualifier values (language, scale, contrast, and so on). 既定のコンテキストでは、上書きされない限り、それぞれの修飾子の値に対してアプリの現在の構成が使われます。A default context uses the app's current configuration for each qualifier value, unless overridden. たとえば、画像などのリソースはスケールで修飾することができます。スケールはモニターごとに異なり、したがってアプリケーション ビューごとに異なります。For example, resources such as images can be qualified for scale, which varies from one monitor to another and hence from one application view to another. この理由から、アプリケーション ビューはそれぞれ別個の既定のコンテキストを持ちます。For this reason, each application view has a distinct default context. 特定のビューの既定のコンテキストは ResourceContext.GetForCurrentView を使って取得することができます。The default context for a given view can be obtained using ResourceContext.GetForCurrentView. リソース候補を取得するときは常に ResourceContext インスタンスを渡して、特定のビューに最も適した値を取得する必要があります。Whenever you retrieve a resource candidate, you should pass in a ResourceContext instance to obtain the most appropriate value for a given view.

重要な APIImportant APIs