URI de paquet dans WPF

Dans Windows Presentation Foundation (WPF), les URI (Uniform Resource Identifier) sont utilisés pour identifier et charger des fichiers de plusieurs façons, notamment :

• Spécification de l’interface utilisateur (IU) à afficher lors du premier démarrage d’une application.

• Chargement d’images.

• Navigation dans les pages.

• Chargement de fichiers de données non exécutables.

En outre, les URI peuvent être utilisés pour identifier et charger des fichiers à partir d’un large éventail d’emplacements, notamment :

• L'assemblée actuelle.

• Assembly référencé.

• Emplacement relatif à un assemblage.

• Site d’origine de l’application.

Pour fournir un mécanisme cohérent pour identifier et charger ces types de fichiers à partir de ces emplacements, WPF tire parti de l’extensibilité du schéma d’URI du pack. Cette rubrique fournit une vue d’ensemble du schéma, explique comment construire des URI de pack pour divers scénarios, décrit les URI absolus et relatifs et la résolution d’URI, avant de montrer comment utiliser des URI de pack à partir du balisage et du code.

Schéma d’URI pack

Le schéma d’URI pack est utilisé par la spécification OPC (Open Packaging Conventions ), qui décrit un modèle d’organisation et d’identification du contenu. Les éléments clés de ce modèle sont des packages et des parties, où un package est un conteneur logique pour une ou plusieurs parties logiques. La figure suivante illustre ce concept.

Pour identifier les parties, la spécification OPC utilise l'extensibilité de RFC 2396 (Identificateurs de Ressources Uniformes (URI) : Syntaxe Générique) pour définir le schéma URI de paquet.

Le schéma spécifié par un URI est défini par son préfixe ; http, ftp et fichier sont des exemples connus. Le schéma d’URI de pack utilise « pack » comme schéma et contient deux composants : l’autorité et le chemin d’accès. Voici le format d'un URI de pack.

chemin d’accès pack:// /

L'autorité spécifie le type de paquet dans lequel un composant est contenu, tandis que le chemin d'accès spécifie l'emplacement d'une partie dans un paquet.

Ce concept est illustré par la figure suivante :

Les packages et les parties sont analogues aux applications et aux fichiers, où une application (package) peut inclure un ou plusieurs fichiers (parties), notamment :

• Fichiers de ressources compilés dans l'assemblage local.

• Fichiers de ressources compilés dans un assembly référencé.

• Fichiers de ressources compilés dans un assembly de référencement.

• Fichiers de contenu.

• Site des fichiers d’origine.

Pour accéder à ces types de fichiers, WPF prend en charge deux autorités : application:/// et siteoforigin:///. L’autorité de application:/// identifie les fichiers de données d’application connus au moment de la compilation, y compris les fichiers de ressources et de contenu. L’autorité de siteoforigin:/// identifie le site des fichiers d’origine. L’étendue de chaque autorité est illustrée dans la figure suivante.

Les sections suivantes expliquent comment construire des URI de pack à l’aide de ces deux autorités conjointement avec les chemins d’accès appropriés pour identifier les fichiers de ressources, de contenu et de site d’origine.

URI du pack de fichiers de ressources

Les fichiers de ressources sont configurés en tant qu’éléments MSBuild Resource et sont compilés en assemblys. WPF prend en charge la création d'URI de pack pouvant être utilisés pour identifier les fichiers de ressources soit compilés dans l'assembly local, soit compilés dans un assembly auquel l'assembly local fait référence.

Fichier de ressources d'assemblage local

L’URI de pack pour un fichier de ressources compilé dans l’assembly local utilise l’autorité et le chemin d’accès suivants :

• Autorité : application:///.

• Chemin d’accès : nom du fichier de ressources, y compris son chemin d’accès, par rapport à la racine du dossier du projet d’assembly local.

L’exemple suivant montre l’URI de pack pour un fichier de ressources XAML situé à la racine du dossier de projet de l’assembly local.

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

L’exemple suivant montre l’URI de pack d’un fichier de ressources XAML situé dans un sous-dossier du dossier de projet de l’assembly local.

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

Fichier de ressources d’assembly référencé

L’URI de pack pour un fichier de ressources compilé dans un assembly référencé utilise l’autorité et le chemin d’accès suivants :

• Autorité : application:///.

• Chemin d’accès : nom d’un fichier de ressources compilé dans un assembly référencé. Le chemin d’accès doit être conforme au format suivant :

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

  • AssemblyShortName : nom court de l’assembly référencé.

  • ; ; Version [facultative] : version de l’assembly référencé qui contient le fichier de ressources. Ceci est utilisé lorsque deux ou plusieurs assemblées référencées avec le même nom abrégé sont chargées.

  • ; ; PublicKey [facultatif] : clé publique utilisée pour signer l’assembly référencé. Ceci est utilisé lorsque deux ou plusieurs assemblées référencées avec le même nom abrégé sont chargées.

  • ; ; composant : spécifie que l’assembly référencé est référencé à partir de l’assembly local.

  • /Path : nom du fichier de ressources, y compris son chemin, par rapport à la racine du dossier de projet de l’assembly référencé.

L’exemple suivant montre l’URI de pack d’un fichier de ressources XAML situé à la racine du dossier de projet de l’assembly référencé.

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

L’exemple suivant montre l’URI de pack d’un fichier de ressources XAML situé dans un sous-dossier du dossier de projet de l’assembly référencé.

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

L'exemple suivant montre l'URI de pack d'un fichier de ressources XAML situé dans le dossier racine du projet d'un assembly référencé et spécifique à une version.

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

Notez que la syntaxe d’URI du pack pour les fichiers de ressources d’assembly référencés ne peut être utilisée qu’avec l’autorité de application:///. Par exemple, les éléments suivants ne sont pas pris en charge dans WPF.

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

URIs de l'ensemble de fichiers de contenu

L’URI de pack d’un fichier de contenu utilise l’autorité et le chemin d’accès suivants :

• Autorité : application:///.

• Chemin d’accès : nom du fichier de contenu, y compris son chemin d’accès par rapport à l’emplacement du système de fichiers de l’assembly exécutable principal de l’application.

L’exemple suivant montre l’URI de pack d’un fichier de contenu XAML, situé dans le même dossier que l’assembly exécutable.

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

L’exemple suivant montre l’URI de pack pour un fichier de contenu XAML, situé dans un sous-dossier relatif à l’assembly exécutable de l’application.

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

URI du pack Site d’origine

L’URI de pack pour un fichier du site d'origine utilise l’autorité et le chemin d’accès suivants :

• Autorité : siteoforigin:///.

• Chemin d’accès : nom du fichier de site d’origine, y compris son chemin d’accès relatif à l’emplacement à partir duquel l’assembly exécutable a été lancé.

L’exemple suivant montre l’URI de pack pour un fichier de site d’origine XAML, stocké à l’emplacement à partir duquel l’assembly exécutable est lancé.

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

L’exemple suivant montre l’URI de pack pour un fichier de site d’origine XAML, stocké dans un sous-dossier relatif à l’emplacement à partir duquel l’assembly exécutable de l’application est lancé.

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

Fichiers de page

Les fichiers XAML configurés en tant qu’éléments MSBuild Page sont compilés dans des assemblys de la même façon que les fichiers de ressources. Par conséquent, les éléments MSBuild Page peuvent être identifiés à l’aide d’URI de pack pour les fichiers de ressources.

Les types de fichiers XAML couramment configurés en tant qu’éléments MSBuildPage ont l’un des éléments suivants comme élément racine :

• System.Windows.Window

• System.Windows.Controls.Page

• System.Windows.Navigation.PageFunction<T>

• System.Windows.ResourceDictionary

• System.Windows.Documents.FlowDocument

• System.Windows.Controls.UserControl

URI de Pack Absolues vs Relatives

Un URI de pack complet inclut le schéma, l’autorité et le chemin, et il est considéré comme un URI de pack absolu. En guise de simplification pour les développeurs, les éléments XAML vous permettent généralement de définir les attributs appropriés avec un URI de pack relatif, qui inclut uniquement le chemin d’accès.

Par exemple, considérez l’URI de pack absolu suivant pour un fichier de ressources dans l’assembly local.

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

L’URI du pack relatif qui fait référence à ce fichier de ressources serait le suivant.

/ResourceFile.xaml

Par défaut, un URI de pack relatif est considéré par rapport à l’emplacement du balisage ou du code qui contient la référence. Si une barre oblique inverse principale est utilisée, toutefois, la référence d’URI du pack relatif est alors considérée par rapport à la racine de l’application. Par exemple, considérez la structure de projet suivante.

App.xaml

Page2.xaml

\SubFolder

+ Page1.xaml

+ Page2.xaml

Si Page1.xaml contient un URI qui fait référence à Root\SubFolder\Page2.xaml, la référence peut utiliser l’URI de pack relatif suivant.

Page2.xaml

Si Page1.xaml contient un URI qui référence Root\Page2.xaml, la référence peut utiliser l’URI de pack relatif suivant.

/Page2.xaml

Résolution d'URI de pack

Le format des URI de pack permet aux URI de pack pour différents types de fichiers de ressembler. Par exemple, considérez l’URI de pack absolu suivant.

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

Cet URI de pack absolu peut faire référence à un fichier de ressources dans l’assembly local ou à un fichier de contenu. Il en va de même pour l’URI relatif suivant.

/ResourceOrContentFile.xaml

Pour déterminer le type de fichier auquel fait référence un URI de pack, WPF résout les URI des fichiers de ressources dans les assemblys locaux et les fichiers de contenu à l’aide des heuristiques suivantes :

1. Sondez les métadonnées d’assembly pour un AssemblyAssociatedContentFileAttribute attribut qui correspond à l’URI du pack.

2. Si l’attribut AssemblyAssociatedContentFileAttribute est trouvé, le chemin d’accès de l’URI du pack fait référence à un fichier de contenu.

3. Si l’attribut AssemblyAssociatedContentFileAttribute est introuvable, sondez les fichiers de ressources définis qui sont compilés dans l’assembly local.

4. Si un fichier de ressources qui correspond au chemin d’accès de l’URI du pack est trouvé, le chemin d’accès de l’URI du pack fait référence à un fichier de ressources.

5. Si la ressource est introuvable, la ressource créée Uri en interne n’est pas valide.

La résolution d’URI ne s’applique pas aux URI qui font référence aux éléments suivants :

• Fichiers de contenu dans les assemblys référencés : ces types de fichiers ne sont pas pris en charge par WPF.

• Fichiers incorporés dans des assemblys référencés : les URI qui les identifient sont uniques, car ils incluent à la fois le nom de l’assembly référencé et le ;component suffixe.

• Fichiers de site d’origine : les URI qui les identifient sont uniques, car ils sont les seuls fichiers qui peuvent être identifiés par des URI de pack qui contiennent l’autorité de siteoforigin:///.

Une simplification de la résolution d’URI de pack permet au code d’être un peu indépendant des emplacements des fichiers de ressources et de contenu. Par exemple, si vous disposez d’un fichier de ressources dans l’assembly local qui est reconfiguré pour être un fichier de contenu, l’URI de pack de la ressource reste identique, comme le code qui utilise l’URI du pack.

Programmation avec des URI pack

De nombreuses classes WPF implémentent des propriétés qui peuvent être définies avec des URI de pack, notamment :

• Application.StartupUri

• Frame.Source

• NavigationWindow.Source

• Hyperlink.NavigateUri

• Window.Icon

• Image.Source

Ces propriétés peuvent être définies à partir du balisage et du code. Cette section présente les constructions de base pour les deux, puis présente des exemples de scénarios courants.

Utilisation d’URI pack dans le balisage

Un URI de pack est spécifié dans le balisage en définissant l’élément d’un attribut avec l’URI de pack. Par exemple:

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

Le tableau 1 illustre les différentes URI de pack absolus que vous pouvez spécifier dans le balisage.

Tableau 1 : URI de pack absolu dans le balisage

Le tableau 2 illustre les différentes URI de pack relatif que vous pouvez spécifier dans le balisage.

Tableau 2 : URIs relatives de pack dans le balisage

Utilisation des URIs pack dans le code

Vous spécifiez un URI de pack dans le code en instanciant la Uri classe et en transmettant l’URI de pack en tant que paramètre au constructeur. Ceci est illustré dans l’exemple suivant.

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

Par défaut, la Uri classe considère que les URI de pack sont absolus. Par conséquent, une exception est levée lorsqu’une instance de la Uri classe est créée avec un URI de pack relatif.

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

Heureusement, la Uri(String, UriKind) surcharge du constructeur de Uri classe accepte un paramètre de type UriKind pour vous permettre de spécifier si un URI de pack est absolu ou relatif.

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

Vous devez spécifier uniquement Absolute ou Relative lorsque vous êtes certain que l’URI de pack fourni est l’un ou l’autre. Si vous ne connaissez pas le type d’URI de pack utilisé, par exemple lorsqu’un utilisateur entre un URI de pack au moment de l’exécution, utilisez RelativeOrAbsolute à la place.

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

Le tableau 3 illustre les différentes URI de pack relatif que vous pouvez spécifier dans le code en utilisant System.Uri à l’aide de.

Tableau 3 : URI de package absolues dans le code

Le tableau 4 illustre les différentes URI de pack relatif que vous pouvez spécifier dans le code à l’aide de System.Uri.

Tableau 4 : URI de pack relatif dans le code

Scénarios d’URI de pack courants

Les sections précédentes ont expliqué comment construire des URI de pack pour identifier les fichiers de ressources, de contenu et de site d’origine. Dans WPF, ces constructions sont utilisées de différentes façons, et les sections suivantes couvrent plusieurs utilisations courantes.

Spécification de l’interface utilisateur à afficher au démarrage d’une application

StartupUri spécifie la première interface utilisateur à afficher lorsqu’une application WPF est lancée. Pour les applications autonomes, l’interface utilisateur peut être une fenêtre, comme illustré dans l’exemple suivant.

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

Les applications autonomes et les applications de navigateur XAML (XBAPs) peuvent également spécifier une page comme interface utilisateur initiale, comme illustré dans l’exemple suivant.

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

Si l’application est une application autonome et qu’une page est spécifiée avec StartupUri, WPF ouvre une NavigationWindow page pour héberger la page. Pour les XBAP, la page s’affiche dans le navigateur hôte.

Navigation vers une page

L’exemple suivant montre comment accéder à une page.

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

Pour plus d’informations sur les différentes façons de naviguer dans WPF, consultez Vue d’ensemble de la navigation.

Spécification d’une icône de fenêtre

L’exemple suivant montre comment utiliser un URI pour spécifier l’icône d’une fenêtre.

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

Pour plus d’informations, consultez Icon.

Chargement des fichiers image, audio et vidéo

WPF permet aux applications d’utiliser un large éventail de types multimédias, qui peuvent tous être identifiés et chargés avec des URI de pack, comme illustré dans les exemples suivants.

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

Pour plus d’informations sur l’utilisation du contenu multimédia, consultez Graphics and Multimedia.

Chargement d’un dictionnaire de ressources à partir du site d’origine

Les dictionnaires de ressources (ResourceDictionary) peuvent être utilisés pour prendre en charge les thèmes d’application. Une façon de créer et de gérer des thèmes consiste à créer plusieurs thèmes en tant que dictionnaires de ressources situés sur le site d’origine d’une application. Cela permet aux thèmes d’être ajoutés et mis à jour sans recompiler et redéployer une application. Ces dictionnaires de ressources peuvent être identifiés et chargés à l’aide d’URI de pack, qui est illustré dans l’exemple suivant.

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

Pour obtenir une vue d’ensemble des thèmes dans WPF, consultez Style et Modélisation.

Voir aussi

• Ressources d'application WPF, contenu et fichiers de données