Paket-URI:er i WPF

I Windows Presentation Foundation (WPF) används enhetliga resursidentifierare (URI:er) för att identifiera och läsa in filer på många sätt, inklusive följande:

• Ange användargränssnittet som ska visas när ett program startar.

• Läser in bilder.

• Navigera till sidor.

• Läser in datafiler som inte kan köras.

Dessutom kan URI:er användas för att identifiera och läsa in filer från en mängd olika platser, inklusive följande:

• Den aktuella sammansättningen.

• En refererad sammanställning.

• En plats i förhållande till en sammansättning.

• Programmets ursprungsplats.

För att tillhandahålla en konsekvent mekanism för att identifiera och läsa in dessa typer av filer från dessa platser utnyttjar WPF utökningsbarheten för paketets URI-schema. Det här avsnittet innehåller en översikt över schemat, beskriver hur du skapar paket-URI:er för en mängd olika scenarier, diskuterar absoluta och relativa URI:er och URI-upplösning, innan du visar hur du använder paket-URI:er från både markering och kod.

Pack URI-schemat

Paketets URI-schema används av OPC-specifikationen ( Open Packaging Conventions ), som beskriver en modell för att organisera och identifiera innehåll. De viktigaste elementen i den här modellen är paket och delar, där ett paket är en logisk container för en eller flera logiska delar. Följande bild illustrerar det här begreppet.

För att identifiera delar utnyttjar OPC-specifikationen utökningsbarheten för RFC 2396 (URI (Uniform Resource Identifiers): Generic Syntax) för att definiera paketets URI-schema.

Schemat som anges av en URI definieras av dess prefix. http, ftp och fil är välkända exempel. Paketets URI-schema använder "pack" som sitt schema och innehåller två komponenter: utfärdare och sökväg. Följande är formatet för en pack-URI.

sökväg pack:// /

Myndigheten anger vilken typ av paket som en del ingår i, medan sökvägen anger platsen för en del inom ett paket.

Det här konceptet illustreras av följande bild:

Paket och delar är analoga med program och filer, där ett program (paket) kan innehålla en eller flera filer (delar), inklusive:

• Resursfiler som kompileras till den lokala assemblyn.

• Resursfiler som kompileras till en refererad sammansättning.

• Resursfiler som kompileras till en refererande sammansättning.

• Innehållsfiler.

• Ursprungsplatsens filer.

För att få åtkomst till dessa typer av filer stöder WPF två myndigheter: application:/// och siteoforigin:///. Den application:/// auktoriteten identifierar programdatafiler som är kända vid kompileringstid, inklusive resurs- och innehållsfiler. siteoforigin:/// auktoritet identifierar ursprungsfiler. Omfånget för varje myndighet visas i följande bild.

I följande avsnitt beskrivs hur du skapar paket-URI:er med hjälp av dessa två myndigheter tillsammans med lämpliga sökvägar för att identifiera resurs-, innehålls- och ursprungsfiler.

URI:er för resursfilpaket

Resursfiler konfigureras som MSBuild-objekt Resource och kompileras till sammansättningar. WPF stöder konstruktion av paket-URI:er som kan användas för att identifiera resursfiler som antingen kompileras till den lokala sammansättningen eller kompileras till en sammansättning som refereras från den lokala sammansättningen.

Resursfil för lokal sammansättning

Paket-URI:n för en resursfil som är inbyggd i den lokala assemblyn använder följande auktoritet och sökväg:

• Utfärdare: application:///.

• Sökväg: Namnet på resursfilen, inklusive dess sökväg, i förhållande till roten för den lokala assembly-projektets mapp.

I följande exempel visas paket-URI:n för en XAML-resursfil som finns i roten i den lokala sammansättningens projektmapp.

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

I följande exempel visas paket-URI:n för en XAML-resursfil som finns i en undermapp i den lokala sammansättningens projektmapp.

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

Refererad sammansättningsresursfil

Paket-URI:n för en resursfil som kompileras till en refererad sammansättning använder följande utfärdare och sökväg:

• Utfärdare: application:///.

• Sökväg: Namnet på en resursfil som kompileras till en refererad samling. Sökvägen måste överensstämma med följande format:

  AssemblyShortName{; Version]{; PublicKey]; komponent/sökväg

  • AssemblyShortName: det korta namnet för den refererade sammansättningen.

  • ; Version [valfritt]: den version av den refererade sammansättningen som innehåller resursfilen. Detta används när två eller flera refererade sammansättningar med samma korta namn läses in.

  • ; PublicKey [valfritt]: den offentliga nyckel som användes för att signera den refererade sammansättningen. Detta används när två eller flera refererade sammansättningar med samma korta namn läses in.

  • ; komponent: anger att sammansättningen som refereras till refereras från den lokala sammansättningen.

  • /Path: namnet på resursfilen, inklusive dess sökväg, i förhållande till roten i den refererade sammansättningens projektmapp.

I följande exempel visas paket-URI:n för en XAML-resursfil som finns i roten i den refererade sammansättningens projektmapp.

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

I följande exempel visas paket-URI:n för en XAML-resursfil som finns i en undermapp i den refererade sammansättningens projektmapp.

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

I följande exempel visas paket-URI:n för en XAML-resursfil som finns i rotmappen för en refererad, versionsspecifik sammansättnings projektmapp.

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

Observera att pack-URI-syntaxen för refererade sammansättningsresursfiler endast kan användas med application:/// auktoritet. Följande stöds till exempel inte i WPF.

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

URI:er för innehållsfilpaket

Paket-URI:n för en innehållsfil använder följande utfärdare och sökväg:

• Utfärdare: application:///.

• Sökväg: Namnet på innehållsfilen, inklusive dess sökväg i förhållande till filsystemets plats för programmets huvudsakliga körbara sammansättning.

I följande exempel visas paket-URI:n för en XAML-innehållsfil som finns i samma mapp som den körbara sammansättningen.

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

I följande exempel visas paket-URI:n för en XAML-innehållsfil som finns i en undermapp som är relativ till programmets körbara sammansättning.

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

URI:er för ursprungspaketplatsen

Paket-URI:n för en ursprungsfilsplats använder följande myndighet och sökväg:

• Utfärdare: siteoforigin:///.

• Sökväg: Namnet på ursprungsfilens plats, inklusive dess sökväg i förhållande till den plats från vilken den körbara sammansättningen startades.

I följande exempel visas paket-URI:n för en XAML-ursprungsfil som lagras på den plats där den körbara sammansättningen startas.

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

I följande exempel visas paket-URI:n för en XAML-plats för ursprungsfilen, lagrad i undermapp som är relativ till den plats från vilken programmets körbara sammansättning startas.

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

Sidfiler

XAML-filer som är konfigurerade som MSBuild-objekt Page kompileras till sammansättningar på samma sätt som resursfiler. Därför kan MSBuild-objekt Page identifieras med hjälp av paket-URI:er för resursfiler.

De typer av XAML-filer som ofta konfigureras som MSBuild-objektPage har något av följande som rotelement:

• System.Windows.Window

• System.Windows.Controls.Page

• System.Windows.Navigation.PageFunction<T>

• System.Windows.ResourceDictionary

• System.Windows.Documents.FlowDocument

• System.Windows.Controls.UserControl

URI:er för absoluta eller relativa paket

En fullständigt kvalificerad pack-URI innehåller schemat, utfärdaren och sökvägen, och det anses vara en absolut pack-URI. Som en förenkling för utvecklare tillåter XAML-element vanligtvis att du anger lämpliga attribut med en relativ pack-URI, som endast innehåller sökvägen.

Tänk till exempel på följande absoluta pack-URI för en resursfil i den lokala sammansättningen.

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

Den relativa pack-URI som refererar till den här resursfilen skulle vara följande.

/ResourceFile.xaml

Som standard betraktas en relativ pack-URI i förhållande till platsen för den markering eller kod som innehåller referensen. Om ett inledande backslash används anses dock den relativa pack-URI-referensen vara relativ till programmets rot. Tänk till exempel på följande projektstruktur.

App.xaml

Page2.xaml

\SubFolder

+ Page1.xaml

+ Page2.xaml

Om Page1.xaml innehåller en URI som refererar till Root\SubFolder\Page2.xaml kan referensen använda följande relativa pack-URI.

Page2.xaml

Om Page1.xaml innehåller en URI som refererar till Root\Page2.xaml kan referensen använda följande relativa pack-URI.

/Page2.xaml

Paket-URI-upplösning

Formatet för paket-URI:er gör det möjligt för paket-URI:er för olika typer av filer att se likadana ut. Tänk till exempel på följande absoluta pack-URI.

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

Den här absoluta pack-URI:n kan referera till antingen en resursfil i den lokala sammansättningen eller en innehållsfil. Detsamma gäller för följande relativa URI.

/ResourceOrContentFile.xaml

För att fastställa vilken typ av fil som en paket-URI refererar till löser WPF URI:er för resursfiler i lokala sammansättningar och innehållsfiler med hjälp av följande heuristik:

1. Avsöka sammansättningsmetadata för ett AssemblyAssociatedContentFileAttribute attribut som matchar paket-URI:n.

2. Om attributet AssemblyAssociatedContentFileAttribute hittas refererar sökvägen till paket-URI:n till en innehållsfil.

3. Om attributet AssemblyAssociatedContentFileAttribute inte hittas avsöker du de angivna resursfilerna som kompileras till den lokala sammansättningen.

4. Om en resursfil som matchar sökvägen till pack-URI:n hittas refererar sökvägen till pack-URI:n till en resursfil.

5. Om resursen inte hittas är den internt skapade Uri ogiltig.

URI-upplösning gäller inte för URI:er som refererar till följande:

• Innehållsfiler i refererade sammansättningar: dessa filtyper stöds inte av WPF.

• Inbäddade filer i refererade sammansättningar: URI:er som identifierar dem är unika eftersom de innehåller både namnet på den refererade sammansättningen och suffixet ;component .

• Ursprungsplatsfiler: De URI:er som identifierar dem är unika eftersom de är de enda filer som kan identifieras av paket-URI:er som innehåller siteoforigin:/// auktoritet.

En förenkling som pack-URI-upplösning tillåter är att koden är något oberoende av platserna för resurs- och innehållsfiler. Om du till exempel har en resursfil i den lokala sammansättningen som är omkonfigurerad för att vara en innehållsfil förblir paket-URI:n för resursen densamma, liksom koden som använder pack-URI:n.

Programmering med URI:er för paket

Många WPF-klasser implementerar egenskaper som kan anges med paket-URI:er, inklusive:

• Application.StartupUri

• Frame.Source

• NavigationWindow.Source

• Hyperlink.NavigateUri

• Window.Icon

• Image.Source

Dessa egenskaper kan anges från både markering och kod. Det här avsnittet visar de grundläggande konstruktionerna för båda och visar sedan exempel på vanliga scenarier.

Använda Pack URI:er i markup

En pack-URI anges i markup genom att sätta elementet för ett attribut med pack-URI. Till exempel:

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

Tabell 1 illustrerar de olika absoluta paket-URI:er som du kan ange i markering.

Tabell 1: URI:er för absoluta paket i markup

Tabell 2 illustrerar de olika relativa paket-URI:er som du kan ange i markering.

Tabell 2: Relativa paket-URI:ar i markup

Använda URI:er för paket i kod

Du anger en pack-URI i kod genom att instansiera Uri klassen och skicka paket-URI:n som en parameter till konstruktorn. Detta visas i följande exempel.

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

Klassen anser som standard Uri att paket-URI:er är absoluta. Därför utlöses ett undantag när en instans av Uri klassen skapas med en relativ pack-URI.

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

Som tur är accepterar överbelastningen Uri(String, UriKind)Uri av klasskonstruktorn en parameter av typen UriKind så att du kan ange om en paket-URI antingen är absolut eller relativ.

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

Du bör ange endast Absolute eller Relative när du är säker på att den angivna paket-URI:n är antingen den ena eller den andra. Om du inte vet vilken typ av pack-URI som används, till exempel när en användare anger en pack-URI vid körning, använder du RelativeOrAbsolute i stället.

// Relative or Absolute URI provided by user via a text box
TextBox userProvidedUriTextBox = new TextBox();
Uri uri = new Uri(userProvidedUriTextBox.Text, UriKind.RelativeOrAbsolute);

Tabell 3 illustrerar de olika relativa paket-URI:er som du kan ange i kod med hjälp av System.Uri.

Tabell 3: URI:er för absoluta paket i kod

Tabell 4 illustrerar de olika relativa paket-URI:er som du kan ange i kod med hjälp av System.Uri.

Tabell 4: Relativa paket-URI:er i kod

Vanliga pack-URI-scenarier

I föregående avsnitt har vi gått igenom hur du skapar paket-URI:er för att identifiera resurs-, innehålls- och ursprungsfiler. I WPF används dessa konstruktioner på flera olika sätt, och följande avsnitt beskriver flera vanliga användningar.

Ange användargränssnittet för att visa när ett program startar

StartupUri anger det första användargränssnittet som visas när ett WPF-program startas. För fristående program kan användargränssnittet vara ett fönster, som du ser i följande exempel.

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

Fristående program och XAML-webbläsarprogram (XBAPs) kan också ange en sida som det ursprungliga användargränssnittet, som du ser i följande exempel.

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

Om programmet är ett fristående program och en sida anges med StartupUriöppnar WPF en NavigationWindow för att vara värd för sidan. För XBAP:er visas sidan i värdwebbläsaren.

Navigera till en sida

I följande exempel visas hur du navigerar till en sida.

<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>

Mer information om de olika sätten att navigera i WPF finns i Navigeringsöversikt.

Ange en fönsterikon

I följande exempel visas hur du använder en URI för att ange ett fönsters ikon.

<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>

Mer information finns i Icon.

Läsa in bild-, ljud- och videofiler

WPF gör det möjligt för program att använda en mängd olika medietyper, som alla kan identifieras och läsas in med paket-URI:er, enligt följande exempel.

<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" />

Mer information om hur du arbetar med medieinnehåll finns i Grafik och multimedia.

Läser in en resursordlista från ursprungsplatsen

Resursordlistor (ResourceDictionary) kan användas för att stödja programteman. Ett sätt att skapa och hantera teman är att skapa flera teman som resursordlistor som finns på ett programs ursprungsplats. Detta gör att teman kan läggas till och uppdateras utan att omkompilera och distribuera om ett program. Dessa resursordlistor kan identifieras och läsas in med hjälp av paket-URI:er, vilket visas i följande exempel.

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

En översikt över teman i WPF finns i Formatering och templating.

Se även

• WPF-programresurs, innehåll och datafiler