URI à en-tête pack dans WPF
Dans Windows Presentation Foundation (WPF), des uniform resource identifiers (URIs) sont utilisés pour identifier et charger des fichiers de différentes manières, notamment :
en spécifiant l'user interface (UI) à afficher au premier démarrage d'une application ;
en chargeant des images ;
en accédant à des pages ;
en chargeant des fichiers de données non exécutables.
En outre, les URIs peuvent être utilisés pour identifier et charger des fichiers à partir de divers 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 d'identification et de chargement de ces types de fichiers à partir de ces emplacements, WPF tire parti de l'extensibilité du modèle URI à en-tête pack. Cette rubrique fournit une vue d'ensemble du modèle, explique comment construire des URIs à en-tête pack pour divers scénarios, décrit la résolution des URIs et URI absolus et relatifs et enfin, démontre comment utiliser les URIs à en-tête pack à partir des balises et du code.
Cette rubrique comprend les sections suivantes.
- Modèle URI à en-tête pack
- URI à en-tête pack de fichiers de ressources
- URI à en-tête pack de fichiers de contenu
- URI à en-tête pack du site d'origine
- Fichiers d'échange
- Différences entre les URI à en-tête pack absoluset relatifs
- Résolution des URI à en-tête pack
- Programmation avec des URI à en-tête pack
- Rubriques connexes
Modèle URI à en-tête pack
Le modèle URI à en-tête pack est utilisé par la spécification OPC (Open Packaging Conventions), qui décrit un modèle d'organisation et d'identification de contenu. Les principaux éléments de ce modèle sont des packages et des parties, un package étant le conteneur logique d'une ou de plusieurs parties logiques. La figure suivante illustre ce concept.
Pour identifier des parties, la spécification OPC tire parti de l'extensibilité de la RFC 2396 (Uniform Resource Identifiers (URI): Generic Syntax) pour définir le modèle URI à en-tête pack.
Le modèle spécifié par un URI est défini par son préfixe ; http, ftp et file en sont des exemples connus. Le modèle URI à en-tête pack utilise l'en-tête "pack" comme modèle et contient deux composants : autorité et chemin d'accès. Un URI à en-tête pack se présente au format suivant :
pack://autorité/chemin d'accès
L'autorité désigne le type de package contenant une partie alors que le chemin d'accès indique l'emplacement d'une partie dans un package.
Ce concept est illustré ci-dessous :
Les packages et les parties sont analogues aux applications et aux fichiers, une application (package) pouvant contenir un ou plusieurs fichiers (parties), notamment :
les fichiers de ressources compilés dans l'assembly local ;
les fichiers de ressources compilés dans un assembly référencé ;
les fichiers de ressources compilés dans un assembly de référence ;
les fichiers de contenu ;
les fichiers du 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 connus au moment de la compilation, notamment les fichiers de ressources et de contenu. L'autorité siteoforigin:/// identifie les fichiers du site d'origine. Le domaine de compétence de chaque autorité est indiqué dans la figure suivante.
Remarque |
---|
Le composant d'autorité d'un URI à en-tête pack est un URI incorporé qui pointe vers un package et doit être conforme à la norme RFC 2396.En outre, le caractère « / » doit être remplacé par le caractère « , » et les caractères réservés tels que « % » et « ?» doivent être placés dans une séquence d'échappement.Pour plus d'informations, consultez l'OPC. |
Les sections suivantes expliquent comment construire l'URIs à en-tête 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 du site d'origine.
URI à en-tête pack de fichiers de ressources
Les fichiers de ressources sont configurés en tant qu'éléments MSBuildResourceet sont compilés dans des assemblys. WPF prend en charge la construction des URIs à en-tête pack permettant d'identifier les fichiers de ressources qui sont compilés dans l'assembly local ou dans un assembly référencé à partir de l'assembly local.
Fichier de ressources dans l'assembly local
L'URI à en-tête pack d'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, relatif à la racine du dossier du projet de l'assembly local.
L'exemple suivant illustre l'URI à en-tête pack d'un fichier de ressources XAML qui se trouve dans la racine du dossier du projet de l'assembly local.
pack://application:,,,/ResourceFile.xaml
L'exemple suivant illustre l'URI à en-tête pack d'un fichier de ressources XAML qui se trouve dans un sous-dossier du dossier du projet de l'assembly local.
pack://application:,,,/Subfolder/ResourceFile.xaml
Fichier de ressources dans un assembly référencé
L'URI à en-tête pack d'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 respecter le format suivant :
NomCourtAssembly[;Version][;CléPublique];component/Chemin d'accès
NomCourtAssembly : nom court de l'assembly référencé.
;Version [facultatif] : version de l'assembly référencé qui contient le fichier de ressources. Ce paramètre est utilisé si au moins deux assemblys référencés portant le même nom court sont chargés.
;CléPublique [facultatif] : clé publique utilisée pour signer l'assembly référencé. Ce paramètre est utilisé si au moins deux assemblys référencés portant 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 d'accès : nom du fichier de ressources, y compris son chemin d'accès, relatif à la racine du dossier du projet de l'assembly référencé.
L'exemple suivant illustre l'URI à en-tête pack d'un fichier de ressources XAML qui se trouve dans la racine du dossier du projet de l'assembly référencé.
pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml
L'exemple suivant illustre l'URI à en-tête pack d'un fichier de ressources XAML qui se trouve dans un sous-dossier du dossier du projet de l'assembly référence.
pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml
L'exemple suivant illustre l'URI à en-tête pack d'un fichier de ressources XAML qui se trouve dans le dossier racine du dossier du projet d'un assembly référencé spécifique à la version.
pack://application:,,,/ReferencedAssembly;v1.0.0.1;component/ResourceFile.xaml
Notez que la syntaxe de l'URI à en-tête pack des fichiers de ressources d'un assembly référencé ne peut être utilisée qu'avec l'autorité application:///. Par exemple, WPF ne prend pas en charge ce qui suit :
pack://siteoforigin:,,,/SomeAssembly;component/ResourceFile.xaml
URI à en-tête pack de fichiers de contenu
L'URI à en-tête 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 relatif à l'emplacement dans le système de fichiers de l'assembly exécutable principal de l'application.
L'exemple suivant indique l'URI à en-tête pack d'un fichier de contenu XAML, qui se trouve dans le même dossier que l'assembly exécutable.
pack://application:,,,/ContentFile.xaml
L'exemple suivant indique l'URI à en-tête pack d'un fichier de contenu XAML, qui se trouve dans un sous-dossier relatif à l'assembly exécutable de l'application.
pack://application:,,,/Subfolder/ContentFile.xaml
Remarque |
---|
Il n'est pas possible d'accéder aux fichiers de contenu HTML.Le modèle URI prend uniquement en charge la navigation vers les fichiers HTML qui se trouvent au site d'origine. |
URI à en-tête pack du site d'origine
L'URI à en-tête pack d'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 du 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 indique l'URI à en-tête pack d'un fichier du site d'origine XAML, qui est stocké à l'emplacement à partir duquel l'assembly exécutable est lancé.
pack://siteoforigin:,,,/SiteOfOriginFile.xaml
L'exemple suivant indique l'URI à en-tête pack d'un fichier du site d'origine XAML, qui est 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 comme éléments Page MSBuild sont compilés dans des assemblys de la même façon que les fichiers de ressources. Par conséquent, les éléments Page MSBuild peuvent être identifiés à l'aide des URIs à en-tête pack des fichiers de ressources.
Les types de fichiers XAML généralement configurés comme des éléments Page MSBuild ont l'un des éléments suivants comme racine :
Différences entre les URI à en-tête pack absoluset relatifs
Un URI à en-tête pack complet comprend le modèle, l'autorité et le chemin d'accès, et il est considéré comme un URI à en-tête pack absolu. Par souci de simplification pour les développeurs, les éléments XAML vous permettent en général de définir des attributs appropriés avec un URI à en-tête pack relatif, qui ne comprend que le chemin d'accès.
Prenez par exemple l'URI à en-tête pack absolu suivant d'un fichier de ressources dans l'assembly local.
pack://application:,,,/ResourceFile.xaml
L'URI à en-tête pack qui fait référence à ce fichier de ressources serait le suivant.
/ResourceFile.xaml
Remarque |
---|
Étant donné que les fichiers du site d'origine ne sont pas associés aux assemblys, ils ne peuvent être désignés que par des URIs à en-tête pack absolus. |
Par défaut, un URI à en-tête pack est considéré comme relatif à l'emplacement de la balise ou du code qui contient la référence. Toutefois, si une barre oblique inverse de début est utilisée, la référence de l'URI à en-tête pack relatif est alors considérée comme étant relative à la racine de l'application. Prenez par exemple 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 à Racine\Sous_dossier\Page2.xaml, la référence peut utiliser l'URI à en-tête pack relatif suivant.
Page2.xaml
Si Page1.xaml contient un URI qui fait référence à Racine\Page2.xaml, la référence peut alors utiliser l'URI à en-tête pack relatif suivant.
/Page2.xaml
Résolution des URI à en-tête pack
Le format des URIs à en-tête pack permet d'attribuer la même apparence aux URIs à en-tête pack de différents types de fichiers. Prenez par exemple l'URI à en-tête pack absolu suivant.
pack://application:,,,/ResourceOrContentFile.xaml
Cet URI à en-tête pack absolu pourrait 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 à en-tête pack, WPF résout les URIs des fichiers de ressources dans les assemblys locaux et des fichiers de contenu à l'aide de l'heuristique suivante :
Recherchez dans les métadonnées de l'assembly un attribut AssemblyAssociatedContentFileAttribute correspondant à l'URI à en-tête pack.
Si l'attribut AssemblyAssociatedContentFileAttribute est détecté, le chemin d'accès de l'URI à en-tête pack fait référence à un fichier de contenu.
Si l'attribut AssemblyAssociatedContentFileAttribute est introuvable, recherchez les fichiers de ressources définis qui sont compilés dans l'assembly local.
Si un fichier de ressources correspondant au chemin d'accès de l'URI à en-tête pack est détecté, le chemin d'accès de l'URI à en-tête pack fait référence à un fichier de ressources.
Si la ressource est introuvable, l'Uri créé en interne n'est pas valide.
La résolution de l'URI ne sollicite pas l'URIs qui fait 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 les assemblys référencés : les URIs qui les identifient sont uniques car ils comprennent à la fois le nom de l'assembly référencé et le suffixe ;component.
Fichiers du site d'origine : les URIs qui les identifient sont uniques car ce sont les seuls fichiers qui peuvent être identifiés par des URIs à en-tête pack contenant l'autorité siteoforigin:///.
Une simplification permise par la résolution de l'URI à en-tête pack réside dans le fait que le code peut être quelque peu indépendant des emplacements des fichiers de ressource et de contenu. Par exemple, si l'assembly local contient un fichier de ressources qui est reconfiguré en un fichier de contenu, l'URI à en-tête pack de la ressource reste identique, de même que le code utilisant cet URI.
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 URIs à en-tête pack, notamment :
Ces propriétés peuvent être définies à partir des balises et du code à la fois. Cette section démontre les constructions de base des deux, puis fournit des exemples de scénarios courants.
Utilisation des URI à en-tête pack dans les balises
Un URI à en-tête pack est spécifié dans les balises en définissant l'élément d'un attribut avec l'URI à en-tête pack. Par exemple :
<element attribute="pack://application:,,,/File.xaml" />
Le tableau 1 illustre les différents URIs à en-tête pack absolus que vous pouvez spécifier dans des balises.
Tableau 1 : URI à en-tête pack absolus dans les balises
Fichier |
URI à en-tête 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 l'assembly référencé spécifique à la version |
"pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml" |
Fichier de contenu |
"pack://application:,,,/ContentFile.xaml" |
Fichier de contenu dans un sous-dossier |
"pack://application:,,,/Subfolder/ContentFile.xaml" |
Fichier du site d'origine. |
"pack://siteoforigin:,,,/SOOFile.xaml" |
Fichier du site d'origine dans un sous-dossier |
"pack://siteoforigin:,,,/Subfolder/SOOFile.xaml" |
Le tableau 2 illustre les différents URIs à en-tête pack relatifs que vous pouvez spécifier dans des balises.
Tableau 2 : URI à en-tête pack relatifs dans les balises
Fichier |
URI à en-tête pack relatif |
---|---|
Fichier de ressources dans l'assembly local |
"/ResourceFile.xaml" |
Fichier de ressources dans un sous-dossier de l'assembly local |
"/Subfolder/ResourceFile.xaml" |
Fichier de ressources dans un 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 de contenu dans un sous-dossier |
"/Subfolder/ContentFile.xaml" |
Utilisation des URI à en-tête pack dans le code
Vous spécifiez un URI à en-tête pack dans le code en instanciant la classe Uri et en transmettant l'URI à en-tête pack comme un paramètre au constructeur. Cela est illustré par l'exemple suivant.
Uri uri = new Uri("pack://application:,,,/File.xaml");
Par défaut, la classe Uri considère les URIs à en-tête pack comme étant absolus. Par conséquent, une exception est déclenchée lorsqu'une instance de la classe Uri est créée avec un URI à en-tête pack relatif.
Uri uri = new Uri("/File.xaml");
Heureusement, la surcharge Uri(String, UriKind) du constructeur de classe Uri accepte un paramètre de type UriKind pour vous permettre de spécifier si un URI à en-tête 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 à en-tête pack est l'un ou l'autre. Si vous ne connaissez pas le type d'URI à en-tête pack utilisé, comme c'est le cas lorsqu'un utilisateur entre un URI à en-tête pack au moment de l'exécution, utilisez plutôt RelativeOrAbsolute.
// 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érents URIs à en-tête pack relatifs que vous pouvez spécifier dans le code en utilisant System.Uri.
Tableau 3 : URI à en-tête pack absolus dans le code
Fichier |
URI à en-tête 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 l'assembly référencé spécifique à la 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 de contenu dans un sous-dossier |
Uri uri = new Uri("pack://application:,,,/Subfolder/ContentFile.xaml", UriKind.Absolute); |
Fichier du site d'origine. |
Uri uri = new Uri("pack://siteoforigin:,,,/SOOFile.xaml", UriKind.Absolute); |
Fichier du site d'origine dans un sous-dossier |
Uri uri = new Uri("pack://siteoforigin:,,,/Subfolder/SOOFile.xaml", UriKind.Absolute); |
Le tableau 4 illustre les différents URIs à en-tête pack relatifs que vous pouvez spécifier dans le code en utilisant System.Uri.
Tableau 4 : URI à en-tête pack relatifs dans le code
Fichier |
URI à en-tête 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 de contenu dans un sous-dossier |
Uri uri = new Uri("/Subfolder/ContentFile.xaml", UriKind.Relative); |
Scénarios courants utilisant des URI à en-tête pack
Les sections précédentes ont expliqué comment construire des URIs à en-tête pack pour identifier des fichiers de ressources, de contenu et du site d'origine. Dans WPF, ces constructions sont utilisées de diverses manières et les sections suivantes en décrivent plusieurs usages courants.
Spécification de l'interface utilisateur à afficher au démarrage d'une application
StartupUri spécifie la première UI à afficher lorsqu'une application WPF est lancée. Pour les applications autonomes, l'UI peut être une fenêtre, comme illustré dans l'exemple suivant.
<Application
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
StartupUri="MainWindow.xaml" />
Les applications autonomes et les XAML browser applications (XBAPs) peuvent également spécifier une page comme interface utilisateur initiale, comme illustré dans l'exemple suivant.
<Application
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
StartupUri="HomePage.xaml" />
Si l'application est une application autonome et une page est spécifiée avec StartupUri, WPF ouvre une NavigationWindow pour héberger la page. Pour les XBAPs, la page est affichée dans le navigateur hôte.
Navigation jusqu'à une page
L'exemple suivant indique comment naviguer jusqu'à une page.
<Page
xmlns="https://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 méthodes de navigation dans WPF, consultez Vue d'ensemble de la navigation.
Spécification d'une icône de fenêtre
L'exemple suivant indique comment utiliser un URI pour spécifier l'icône d'une fenêtre.
<Window
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
x:Class="SDKSample.MainWindow"
Icon="WPFIcon1.ico">
</Window>
Pour plus d'informations, consultez Icon.
Chargement de fichiers image, audio et vidéo
WPF permet aux applications d'utiliser une large gamme de types de médias, qui peuvent tous être identifiés et chargés avec les URIs à en-tête 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 de contenus multimédias, 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 des thèmes d'application. Une façon de créer et de gérer des thèmes consiste en la création de plusieurs thèmes, comme des dictionnaires de ressources, qui se trouvent au site d'origine d'une application. Cela permet d'ajouter et de mettre à jour des thèmes sans avoir à recompiler et redéployer une application. Ces dictionnaires de ressources peuvent être identifiés et chargés à l'aide d'URIs à en-tête pack, qui sont illustrés dans l'exemple suivant.
<Application
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
StartupUri="HomePage.xaml">
<Application.Resources>
<ResourceDictionary Source="pack://siteoforigin:,,,/PageTheme.xaml" />
</Application.Resources>
</Application>
Pour une vue d'ensemble des thèmes dans WPF, consultez Application d'un style et création de modèles.
Voir aussi
Concepts
Fichiers de ressources, de contenu et de données d'une application WPF