URI à en-tête pack 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.

• En chargeant des images

• En naviguant vers des pages

• En chargeant des 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’assembly actuel

• Un assembly référencé

• Un emplacement relatif à un assembly

• Le 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 URI à en-tête 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 tire parti de l’extensibilité de RFC 2396 (URI ) pour définir le schéma d’URI de pack.

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

chemin d’accès pack:// authority/

L’autorité spécifie le type de package qui contient une partie, tandis que le chemin spécifie l’emplacement d’une partie dans un package.

Ce concept est illustré par le figure suivante :

Les packages et les parties s’apparentent à des applications et des fichiers, où une application (package) peut inclure un ou plusieurs fichiers (parties), notamment :

• Des fichiers de ressources compilés dans l’assembly local

• Des fichiers de ressources compilés dans un assembly référencé

• Des fichiers de ressources compilés dans un assembly de référence

• Des fichiers de contenu

• Des fichiers de site d’origine

Pour accéder à ces types de fichiers, WPF prend en charge deux autorités : application:/// et siteoforigin:///. L’autorité application:/// identifie les fichiers de données d’application qui sont connus au moment de la compilation, notamment les fichiers de ressources et de contenu. L’autorité siteoforigin:/// identifie les fichiers de site d’origine. La portée de chaque autorité est indiquée dans la figure suivante.

Remarque

Le composant d’autorité d’un URI de pack est un URI incorporé qui pointe vers un package et doit être conforme à RFC 2396. De plus, le caractère « / » doit être remplacé par le caractère « , » et les caractères réservés tels que « % » et « ? » doivent être échappés. Pour plus d’informations, consultez l’OPC.

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 à en-tête pack de fichier 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 construction d’URI de pack qui peuvent être utilisés pour identifier les fichiers de ressources qui sont compilés dans l’assembly local ou compilés dans un assembly référencé à partir de l’assembly local.

Fichier de ressources d’assembly 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 : nom du fichier de ressources, y compris son chemin relatif à la racine du dossier du projet de l’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 : nom d’un fichier de ressources compilé dans un assembly référencé. Le chemin doit respecter le format suivant :

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

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

  • ;Version [facultatif] : version de l’assembly référencé qui contient le fichier de ressources. Elle est utilisée quand plusieurs assemblys référencés ayant le même nom court sont chargés.

  • ;CléPublique [facultatif] : clé publique utilisée pour signer l’assembly référencé. Elle est utilisée quand plusieurs assemblys référencés ayant le même nom court sont chargés.

  • ;component : indique que l’assembly désigné est référencé à partir de l’assembly local.

  • /Chemin : nom du fichier de ressources, y compris son chemin relatif à la racine du dossier du 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 d’un dossier de projet spécifique à la version référencé.

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

URI à en-tête pack de fichier de contenu

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

• Autorité : application:///.

• Chemin : nom du fichier de contenu, y compris son chemin relatif à l’emplacement, dans le 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

Remarque

Impossible d’accéder aux fichiers de contenu HTML. Le schéma d’URI prend uniquement en charge la navigation vers des fichiers HTML situés sur le site d’origine.

URI à en-tête pack de site d’origine

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

• Autorité : siteoforigin:///.

• Chemin : nom du fichier de site d’origine, y compris son chemin 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 d’échange

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 Absolute vs Relative Pack

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

Remarque

Étant donné que les fichiers de site d’origine ne sont pas associés à des assemblys, ils ne peuvent être référencés qu’avec des URI de pack absolus.

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 des URI à en-tête 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 à en-tête 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 décrit les constructions de base pour les deux, et fournit des exemples de scénarios courants.

Utilisation d’URI à en-tête 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 à en-tête pack absolus dans le balisage

Fichier	URI de pack absolu
Fichier de ressources - assembly local	"pack://application:,,,/ResourceFile.xaml"
Fichier de ressources dans un sous-dossier - assembly local	"pack://application:,,,/Subfolder/ResourceFile.xaml"
Fichier de ressources - assembly référencé	"pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml"
Fichier de ressources dans un sous-dossier de l’assembly référencé	"pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
Fichier de ressources dans un assembly référencé avec version	"pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml"
Fichier de contenu	"pack://application:,,,/ContentFile.xaml"
Fichier contenu dans un sous-dossier	"pack://application:,,,/Subfolder/ContentFile.xaml"
Fichier de site d’origine	"pack://siteoforigin:,,,/SOOFile.xaml"
Fichier de site d’origine dans un sous-dossier	"pack://siteoforigin:,,,/Subfolder/SOOFile.xaml"

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

Tableau 2 : URI à en-tête pack relatifs dans le balisage

Fichier	URI du pack relatif
Fichier de ressources dans un assembly local	"/ResourceFile.xaml"
Fichier de ressources dans un sous-dossier de l’assembly local	"/Subfolder/ResourceFile.xaml"
Fichier de ressources dans l’assembly référencé	"/ReferencedAssembly;component/ResourceFile.xaml"
Fichier de ressources dans un sous-dossier de l’assembly référencé	"/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
Fichier de contenu	"/ContentFile.xaml"
Fichier contenu dans un sous-dossier	"/Subfolder/ContentFile.xaml"

Utilisation d’URI à en-tête 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. Cette opération est illustrée 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 à l’aide System.Uride .

Tableau 3 : URI à en-tête pack absolus dans le code

Fichier	URI de pack absolu
Fichier de ressources - assembly local	Uri uri = new Uri("pack://application:,,,/ResourceFile.xaml", UriKind.Absolute);
Fichier de ressources dans un sous-dossier - assembly local	Uri uri = new Uri("pack://application:,,,/Subfolder/ResourceFile.xaml", UriKind.Absolute);
Fichier de ressources - assembly référencé	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Absolute);
Fichier de ressources dans un sous-dossier de l’assembly référencé	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Absolute);
Fichier de ressources dans un assembly référencé avec version	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml", UriKind.Absolute);
Fichier de contenu	Uri uri = new Uri("pack://application:,,,/ContentFile.xaml", UriKind.Absolute);
Fichier contenu dans un sous-dossier	Uri uri = new Uri("pack://application:,,,/Subfolder/ContentFile.xaml", UriKind.Absolute);
Fichier de site d’origine	Uri uri = new Uri("pack://siteoforigin:,,,/SOOFile.xaml", UriKind.Absolute);
Fichier de site d’origine dans un sous-dossier	Uri uri = new Uri("pack://siteoforigin:,,,/Subfolder/SOOFile.xaml", UriKind.Absolute);

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

Tableau 4 : URI à en-tête pack relatifs dans le code

Fichier	URI du pack relatif
Fichier de ressources - assembly local	Uri uri = new Uri("/ResourceFile.xaml", UriKind.Relative);
Fichier de ressources dans un sous-dossier - assembly local	Uri uri = new Uri("/Subfolder/ResourceFile.xaml", UriKind.Relative);
Fichier de ressources - assembly référencé	Uri uri = new Uri("/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Relative);
Fichier de ressources dans un sous-dossier - assembly référencé	Uri uri = new Uri("/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Relative);
Fichier de contenu	Uri uri = new Uri("/ContentFile.xaml", UriKind.Relative);
Fichier contenu dans un sous-dossier	Uri uri = new Uri("/Subfolder/ContentFile.xaml", UriKind.Relative);

Scénarios courants d’URI à en-tête pack

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 adresses XBAPs, la page s’affiche dans le navigateur hôte.

Navigation vers une page

L’exemple suivant montre comment naviguer vers 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 de fichiers vidéo, audio et image

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 Graphiques et multimédia.

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. L’une des façons de créer et de gérer des thèmes consiste à créer plusieurs thèmes en tant que dictionnaires de ressources situés dans le site d’origine d’une application. Ainsi, les thèmes peuvent être ajoutés et mis à jour sans qu’il soit nécessaire de recompiler et de 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 Création de modèles.

Voir aussi

• Fichiers de ressources, de contenu et de données d’une application WPF