WPF 中的 Pack URI

在 Windows Presentation Foundation (WPF) 中，透過多種方式使用統一資源識別項 (URI) 來識別和載入檔案，包括下列項目：

• 指定要在第一次啟動應用程式時顯示的使用者介面 (UI)。

• 載入影像。

• 巡覽至頁面。

• 載入不可執行的資料檔案。

此外，URI 可以用來識別和載入各種位置中的檔案，包括下列項目：

• 目前的組件。

• 所參考的組件。

• 與組件相對的位置。

• 應用程式的來源網站。

為了提供一致的機制來識別和載入這些位置中的這些檔案類型，WPF 利用「Pack URI 配置」的擴充性。 本主題概述配置、涵蓋在顯示如何從標記和程式碼使用 Pack URI 之前如何建構各種案例的 Pack URI，以及討論絕對和相對 URI 及 URI 解析。

套件 URI 配置

Pack URI 配置是供開放式封裝慣例 (OPC) 規格所使用，而此規格描述用於組織和識別內容的模型。 此模型的重要項目是套件和組件，其中「套件」是一或多個邏輯「組件」的邏輯容器。 下圖說明這個概念。

若要識別組件，OPC 規格會利用 RFC 2396 (統一資源識別項 (URI)：泛型語法) 的擴充性來定義 Pack URI 配置。

URI 所指定的配置是透過其前置詞所定義：http、ftp 和 file 是已知範例。 Pack URI 配置使用 "pack" 作為其配置，並包含兩個元件︰authority 和 path。 Pack URI 的格式如下。

pack://authority/path

<授權> 指定包含組件的套件類型，而 <路徑> 指定套件內組件的位置。

下圖說明這個概念︰

套件和組件與應用程式和檔案類似，其中應用程式 (套件) 可以包括一或多個檔案 (組件)，包括︰

• 編譯為本機組件的資源檔。

• 編譯為所參考組件的資源檔。

• 編譯為參考組件的資源檔。

• 內容檔。

• 來源網站檔案。

為了存取這些類型的檔案，WPF 支援兩種授權︰application:/// 和 siteoforigin:///。 application:/// 授權識別在編譯時期已知的應用程式資料檔，包括資源檔和內容檔。 siteoforigin:/// 授權識別來源網站檔案。 下圖顯示每個授權的範圍。

注意

Pack URI 的 authority 元件是內嵌的 URI，可指向套件，並且必須符合 RFC 2396。 此外，"/" 字元必須取代為 "," 字元，而且必須逸出 "%" 和 "?" 這類保留字元。 如需詳細資料，請參閱 OPC。

下列各節說明如何搭配使用這兩個授權與適當路徑來建構 Pack URI，以識別資源、內容和原點網站檔案。

資源檔套件 URI

資源檔案設定為 MSBuild Resource 項目，並編譯為組件。 WPF 支援可用來識別資源檔案的 Pack URI 的建構，而資源檔案編譯為本機組件或編譯為從本機組件所參考的組件。

本機組件資源檔

編譯為本機組件之資源檔案的 Pack URI 會使用下列授權和路徑：

• 授權：application:///。

• 路徑︰相對於本機組件專案資料夾根之資源檔的名稱，包括其路徑。

下列範例顯示 XAML 資源檔案的 Pack URI，而此資源檔案位於本機組件專案資料夾的根資料夾中。

pack://application:,,,/ResourceFile.xaml

下列範例顯示 XAML 資源檔案的 Pack URI，而此資源檔案位於本機組件專案資料夾的子資料夾中。

pack://application:,,,/Subfolder/ResourceFile.xaml

所參考的組件資源檔

編譯為所參考組件之資源檔案的 Pack URI 會使用下列授權和路徑：

• 授權：application:///。

• 路徑：編譯為所參考組件之資源檔的名稱。 路徑必須符合下列格式：

  AssemblyShortName{;Version]{;PublicKey];component/Path

  • AssemblyShortName：所參考組件的簡短名稱。

  • ;Version [選擇性]：包含資源檔之參考組件的版本。 這是在載入具有相同簡短名稱的兩個以上參考組件時使用。

  • ;PublicKey [選擇性]：用來簽署參考組件的公開金鑰。 這是在載入具有相同簡短名稱的兩個以上參考組件時使用。

  • ;component︰指定從本機組件參考所參考的組件。

  • /Path︰相對於所參考組件專案資料夾根之資源檔的名稱，包括其路徑。

下列範例顯示 XAML 資源檔案的 Pack URI，而此檔案位於所參考組件專案資料夾的根資料夾中。

pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml

下列範例顯示 XAML 資源檔案的 Pack URI，而此檔案位於所參考組件專案資料夾的子資料夾中。

pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml

下列範例顯示 XAML 資源檔案的 Pack URI，而此檔案位於所參考版本特定組件專案資料夾的根資料夾中。

pack://application:,,,/ReferencedAssembly;v1.0.0.1;component/ResourceFile.xaml

請注意，所參考組件資源檔案的 Pack URI 語法只能與 application:/// 授權搭配使用。 例如，WPF 中不支援下列項目。

pack://siteoforigin:,,,/SomeAssembly;component/ResourceFile.xaml

內容檔套件 URI

內容檔案的 Pack URI 使用下列授權和路徑：

• 授權：application:///。

• 路徑：內容檔的名稱，包括其相對於應用程式主要可執行組件之檔案系統位置的路徑。

下列範例顯示 XAML 內容檔案的 Pack URI，而此檔案位於與可執行組件相同的資料夾中。

pack://application:,,,/ContentFile.xaml

下列範例顯示 XAML 內容檔案的 Pack URI，而此檔案位於相對於應用程式可執行組件的子資料夾中。

pack://application:,,,/Subfolder/ContentFile.xaml

注意

無法導覽至 HTML 內容檔案。 URI 配置只支援導覽至位於原點網站的 HTML 檔案。

來源網站套件 URI

原點網站檔案的 Pack URI 使用下列授權和路徑：

• 授權：siteoforigin:///。

• 路徑：來源網站檔案的名稱，包括其相對於從中啟動可執行組件之位置的路徑。

下列範例顯示 XAML 原點網站檔案的 Pack URI，而此檔案儲存至從中啟動可執行組件的位置。

pack://siteoforigin:,,,/SiteOfOriginFile.xaml

下列範例顯示 XAML 原點網站檔案的 Pack URI，，而此檔案儲存至相對於從中啟動應用程式可執行組件之位置的子資料夾。

pack://siteoforigin:,,,/Subfolder/SiteOfOriginFile.xaml

分頁檔

設定為 MSBuild Page 項目的 XAML 檔案會編譯為組件，而其編譯方式與資源檔案相同。 因此，MSBuild Page 項目可以使用資源檔案的 Pack URI 進行識別。

通常設定為 MSBuild Page 項目的 XAML 檔案類型會將下列其中一項作為其根元素：

• System.Windows.Window

• System.Windows.Controls.Page

• System.Windows.Navigation.PageFunction<T>

• System.Windows.ResourceDictionary

• System.Windows.Documents.FlowDocument

• System.Windows.Controls.UserControl

絕對與相對套件 URI

完整 Pack URI 包括配置、授權和路徑，而且將其視為絕對 Pack URI。 基於針對開發人員所進行的簡化，XAML 元素一般可讓您設定具有相對 Pack URI 的適當屬性，而相對 Pack URI 只包括路徑。

例如，請考慮使用本機組件中資源檔案的下列絕對 Pack URI。

pack://application:,,,/ResourceFile.xaml

參考此資源檔案的相對 Pack URI 將會如下。

/ResourceFile.xaml

注意

因為原點網站檔案未與組件相關聯，所以只能使用絕對 Pack URI 進行參考。

根據預設，會將相對 Pack URI 視為相對於包含參考之標記或程式碼的位置。 不過，如果使用前置反斜線，則會將相對 Pack URI 參考視為相對於應用程式的根。 例如，請考慮下列專案結構。

App.xaml

Page2.xaml

\SubFolder

+ Page1.xaml

+ Page2.xaml

如果 Page1.xaml 包含可參考 Root\SubFolder\Page2.xaml 的 URI，則該參考可以使用下列相對 Pack URI。

Page2.xaml

如果 Page1.xaml 包含可參考 Root\Page2.xaml 的 URI，則該參考可以使用下列相對 Pack URI。

/Page2.xaml

套件 URI 解析

Pack URI 的格式可讓不同檔案類型的 Pack URI 看起來都相同。 例如，請考慮使用下列絕對 Pack URI。

pack://application:,,,/ResourceOrContentFile.xaml

此絕對 Pack URI 可以參考本機組件中的資源檔案或是內容檔案。 這也適用於下列相對 URI。

/ResourceOrContentFile.xaml

為了判斷 Pack URI 所參考的檔案類型，WPF 會使用下列啟發學習法，來解析本機組件中的資源檔案以及內容檔案的 URI：

1. 探查符合 Pack URI 之 AssemblyAssociatedContentFileAttribute 屬性的組件中繼資料。

2. 如果找到 AssemblyAssociatedContentFileAttribute 屬性，則 Pack URI 的路徑會參考內容檔案。

3. 如果找不到 AssemblyAssociatedContentFileAttribute 屬性，則請探查編譯為本機組件的所設定資源檔案。

4. 如果找到符合 Pack URI 路徑的資源檔案，則 Pack URI 的路徑會參考資源檔案。

5. 如果找不到資源，則內部建立的 Uri 無效。

URI 解析不適用於參考下列項目的 URI：

• 所參考組件中的內容檔︰WPF 不支援這些檔案類型。

• 所參考組件中的內嵌檔案：可識別它們的 URI 是唯一的，因為它們包括所參考組件的名稱和 ;component 尾碼。

• 原點網站檔案：可識別它們的 URI 是唯一的，因為它們是包含 siteoforigin:/// 授權的 Pack URI 可識別的唯一檔案。

Pack URI 解析所允許的一項簡化是讓程式碼成為與資源檔案和內容檔案位置無關的項目。 例如，如果您在本機組件中的資源檔案會重新設定為內容檔案，則資源的 Pack URI 會維持不變，就像使用 Pack URI 的程式碼一樣。

使用套件 URI 的程式設計

許多 WPF 類別都會實作可使用 Pack URI 所設定的屬性，包括：

• Application.StartupUri

• Frame.Source

• NavigationWindow.Source

• Hyperlink.NavigateUri

• Window.Icon

• Image.Source

可以透過標記和程式碼來設定這些屬性。 本節示範兩者的基本建構，並顯示常見案例的範例。

透過標記使用套件 URI

使用 Pack URI 來設定屬性的元素，即可透過標記來指定 Pack URI。 例如：

<element attribute="pack://application:,,,/File.xaml" />

表 1 說明您可以透過標記指定的各種絕對 Pack URI。

表 1：使用標記的絕對套件 URI

檔案	絕對 Pack 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 說明您可以透過標記指定的各種相對 Pack URI。

表 2：使用標記的相對套件 URI

檔案	相對 Pack URI
本機組件中的資源檔	"/ResourceFile.xaml"
本機組件子資料夾中的資源檔	"/Subfolder/ResourceFile.xaml"
參考組件中的資源檔	"/ReferencedAssembly;component/ResourceFile.xaml"
參考組件之子資料夾中的資源檔	"/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
內容檔	"/ContentFile.xaml"
子資料夾中的內容檔	"/Subfolder/ContentFile.xaml"

透過程式碼使用套件 URI

您可以具現化 Uri 類別，並將 Pack URI 以參數形式傳遞給建構函式，以使用程式碼來指定 Pack URI。 這點在下列範例中示範。

Uri uri = new Uri("pack://application:,,,/File.xaml");

根據預設，Uri 類別會將 Pack URI 視為絕對。 因此，使用相對 Pack URI 來建立 Uri 類別的執行個體時，會引發例外狀況。

Uri uri = new Uri("/File.xaml");

幸運的是，Uri 類別建構函式的 Uri(String, UriKind) 多載接受 UriKind 類型的參數，讓您可以指定 Pack URI 是絕對還是相對。

// Absolute URI (default)
Uri absoluteUri = new Uri("pack://application:,,,/File.xaml", UriKind.Absolute);
// Relative URI
Uri relativeUri = new Uri("/File.xaml",
                        UriKind.Relative);

當您確定所提供的 Pack URI 是其中一個或另一個時，應該只指定 Absolute 或 Relative。 如果您不知道使用的 Pack URI 類型 (例如，使用者在執行階段輸入 Pack 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，以透過程式碼指定的各種相對 Pack URI。

表 3：使用程式碼的絕對套件 URI

檔案	絕對 Pack 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，以透過標記指定的各種相對 Pack URI。

表 4：使用程式碼的相對套件 URI

檔案	相對 Pack 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 案例

上述各節已討論如何建構 Pack URI 來識別資源、內容和原點網站檔案。 在 WPF 中，可透過各種方式使用這些建構，而且下列各節涵蓋數種常見用法。

指定要在啟動應用程式時顯示的 UI

StartupUri 指定要在啟動 WPF 應用程式時顯示的第一個 UI。 針對獨立應用程式，UI 可以是視窗，如下列範例所示。

<Application
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    StartupUri="MainWindow.xaml" />

獨立應用程式和 XAML 瀏覽器應用程式 (XBAP) 也可以指定頁面作為初始 UI，如下列範例所示。

<Application
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    StartupUri="HomePage.xaml" />

如果應用程式是獨立應用程式，而且使用 StartupUri 來指定頁面，則 WPF 會開啟 NavigationWindow 來裝載頁面。 針對 XBAP，頁面會顯示在主機瀏覽器中。

巡覽至頁面

下列範例示範如何巡覽至頁面。

<Page
  xmlns="http://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="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  x:Class="SDKSample.MainWindow"
    Icon="WPFIcon1.ico">
</Window>

如需詳細資訊，請參閱Icon。

載入影像、音訊和視訊檔案

WPF 可讓應用程式使用各種媒體類型，而且全部都可以使用 Pack URI 來進行識別和載入，如下列範例所示。

<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) 可以用來支援應用程式主題。 建立和管理主題的一種方法是將多個主題建立為位在應用程式來源網站的資源字典。 這樣可新增和更新主題，而不需要重新編譯和重新部署應用程式的。 使用下列範例所示的 Pack URI，可以識別和載入這些資源字典。

<Application
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    StartupUri="HomePage.xaml">
  <Application.Resources>
    <ResourceDictionary Source="pack://siteoforigin:,,,/PageTheme.xaml" />
  </Application.Resources>
</Application>

如需 WPF 中主題的概觀，請參閱設定樣式和範本。

另請參閱

• WPF 應用程式資源、內容和資料檔案