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

Les applications Microsoft Windows dépendent souvent de fichiers qui contiennent des données non exécutables, telles que XAML (Extensible Application Markup Language), des images, des vidéos et de l’audio. Windows Presentation Foundation (WPF) offre une prise en charge spéciale de la configuration, de l’identification et de l’utilisation de ces types de fichiers de données, appelés fichiers de données d’application. Cette prise en charge repose sur un ensemble spécifique de types de fichier de données d’application, notamment :

• Fichiers de ressources : fichiers de données compilés dans un assembly WPF exécutable ou bibliothèque.

• Fichiers de contenu : fichiers de données autonomes qui ont une association explicite avec un assembly WPF exécutable.

• Fichiers de site d’origine : fichiers de données autonomes qui n’ont aucune association avec un assembly WPF exécutable.

Il existe une distinction importante entre ces trois types de fichier : les fichiers de ressources et les fichiers de contenu sont connus au moment de la génération. En effet, un assembly les connaît explicitement. Toutefois, pour les fichiers de site d’origine, un assembly ne peut avoir aucune connaissance de ces fichiers, ou des connaissances implicites par le biais d’une référence URI (Uniform Resource Identifier) de pack ; le cas de ce dernier, il n’y a aucune garantie que le site référencé du fichier d’origine existe réellement.

Pour référencer les fichiers de données d’application, Windows Presentation Foundation (WPF) utilise le schéma URI (Uniform Resource Identifier) Pack, qui est décrit en détail dans les URI pack dans WPF.

Cette rubrique décrit comment configurer et utiliser des fichiers de données d’application.

Fichiers de ressources

Si un fichier de données d’application doit toujours être disponible pour une application, le seul moyen de garantir cette disponibilité est de le compiler en un assembly exécutable principal d’une application ou en l’un de ses assemblys référencés. Ce type de fichier de données d’application s’appelle un fichier de ressources.

Vous devez utiliser des fichiers de ressources dans les situations suivantes :

• Vous n’avez pas besoin de mettre à jour le contenu du fichier de ressources une fois qu’il a été compilé en un assembly.

• Vous souhaitez simplifier la complexité de distribution d’une application en réduisant le nombre des dépendances de fichiers.

• Votre fichier de données d’application doit être localisable (consultez Vue d’ensemble de la globalisation et de la localisation WPF).

Configuration des fichiers de ressources

Dans WPF, un fichier de ressources est un fichier inclus dans un projet de moteur de build Microsoft (MSBuild) en tant qu’élément Resource .

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ... >  
  ...  
  <ItemGroup>  
    <Resource Include="ResourceFile.xaml" />  
  </ItemGroup>  
  ...  
</Project>  

Lorsque le projet est généré, MSBuild compile la ressource dans l’assembly.

Utilisation des fichiers de ressources

Pour charger un fichier de ressources, vous pouvez appeler la GetResourceStream méthode de la Application classe, en passant un URI de pack qui identifie le fichier de ressources souhaité. GetResourceStream retourne un StreamResourceInfo objet, qui expose le fichier de ressources en tant que Stream type de contenu et décrit son type de contenu.

Par exemple, le code suivant montre comment charger GetResourceStream un Page fichier de ressources et le définir comme contenu d’un Frame (pageFrame) :

// Navigate to xaml page
Uri uri = new Uri("/PageResourceFile.xaml", UriKind.Relative);
StreamResourceInfo info = Application.GetResourceStream(uri);
System.Windows.Markup.XamlReader reader = new System.Windows.Markup.XamlReader();
Page page = (Page)reader.LoadAsync(info.Stream);
this.pageFrame.Content = page;

' Navigate to xaml page
Dim uri As New Uri("/PageResourceFile.xaml", UriKind.Relative)
Dim info As StreamResourceInfo = Application.GetResourceStream(uri)
Dim reader As New System.Windows.Markup.XamlReader()
Dim page As Page = CType(reader.LoadAsync(info.Stream), Page)
Me.pageFrame.Content = page

Lors de l’appel GetResourceStreamStreamvous donne accès, vous devez effectuer le travail supplémentaire de la convertir en type de propriété avec laquelle vous le définirez. Au lieu de cela, vous pouvez laisser WPF s’occuper de l’ouverture et de la conversion du Stream fichier en chargeant un fichier de ressources directement dans la propriété d’un type à l’aide du code.

L’exemple suivant montre comment charger un Page fichier directement dans un Frame (pageFrame) à l’aide de code.

Uri pageUri = new Uri("/PageResourceFile.xaml", UriKind.Relative);
this.pageFrame.Source = pageUri;

Dim pageUri As New Uri("/PageResourceFile.xaml", UriKind.Relative)
Me.pageFrame.Source = pageUri

L’exemple suivant est l’équivalent sous forme de balisage de l’exemple précédent.

<Frame Name="pageFrame" Source="PageResourceFile.xaml" />

Fichiers de code d’application en tant que fichiers de ressources

Un ensemble spécial de fichiers de code d’application WPF peut être référencé à l’aide d’URI de pack, notamment des fenêtres, des pages, des documents de flux et des dictionnaires de ressources. Par exemple, vous pouvez définir la Application.StartupUri propriété avec un URI de pack qui fait référence à la fenêtre ou à la page que vous souhaitez charger au démarrage d’une application.

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

Vous pouvez le faire lorsqu’un fichier XAML est inclus dans un projet MSBuild en tant qu’élément Page .

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ... >  
  ...  
  <ItemGroup>  
    <Page Include="MainWindow.xaml" />  
  </ItemGroup>  
  ...  
</Project>  

Lorsqu’un projet avec Page des éléments est compilé, les éléments XAML sont convertis en format binaire et compilés dans l’assembly associé. Ainsi, ces fichiers peuvent être utilisés de la même façon que des fichiers de ressources classiques.

Fichiers de contenu

Un fichier de contenu est distribué en tant que fichier libre aux côtés d’un assembly exécutable. Bien qu’ils ne soient pas compilés en un assembly, les assemblys sont compilés à l’aide de métadonnées qui établissent une association avec chaque fichier de contenu.

Vous devez utiliser des fichiers de contenu quand votre application nécessite un ensemble spécifique de fichiers de données d’application, que vous souhaitez pouvoir mettre à jour sans recompiler l’assembly qui les consomme.

Configuration des fichiers de contenu

Pour ajouter un fichier de contenu à un projet, un fichier de données d’application doit être inclus en tant qu’élément Content . En outre, étant donné qu’un fichier de contenu n’est pas compilé directement dans l’assembly, vous devez définir l’élément de métadonnées MSBuild CopyToOutputDirectory pour spécifier que le fichier de contenu est copié à un emplacement relatif à l’assembly généré. Si vous souhaitez que la ressource soit copiée dans le dossier de sortie de build chaque fois qu’un projet est généré, vous définissez l’élément CopyToOutputDirectory de métadonnées avec la Always valeur. Sinon, vous pouvez vous assurer que seule la version la plus récente de la ressource est copiée dans le dossier de sortie de build à l’aide de la PreserveNewest valeur.

L’exemple ci-dessous illustre un fichier configuré en tant que fichier de contenu copié dans le dossier de sortie de build uniquement quand une nouvelle version de la ressource est ajoutée au projet.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ... >  
  ...  
  <ItemGroup>  
    <Content Include="ContentFile.xaml">  
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>  
    </Content>  
  </ItemGroup>  
  ...  
</Project>  

Lorsque le projet est généré, un AssemblyAssociatedContentFileAttribute attribut est compilé dans les métadonnées de l’assembly pour chaque fichier de contenu.

[assembly: AssemblyAssociatedContentFile("ContentFile.xaml")]

La valeur de l’élément AssemblyAssociatedContentFileAttribute implique le chemin d’accès au fichier de contenu par rapport à sa position dans le projet. Par exemple, si un fichier de contenu se trouvait dans un sous-dossier de projet, les informations de chemin d’accès supplémentaires seraient incorporées dans la AssemblyAssociatedContentFileAttribute valeur.

[assembly: AssemblyAssociatedContentFile("Resources/ContentFile.xaml")]

La AssemblyAssociatedContentFileAttribute valeur est également la valeur du chemin d’accès au fichier de contenu dans le dossier de sortie de build.

Utilisation des fichiers de contenu

Pour charger un fichier de contenu, vous pouvez appeler la GetContentStream méthode de la Application classe, en transmettant un URI de pack qui identifie le fichier de contenu souhaité. GetContentStream retourne un StreamResourceInfo objet, qui expose le fichier de contenu en tant que Stream type de contenu et décrit son type de contenu.

Par exemple, le code suivant montre comment charger GetContentStream un Page fichier de contenu et le définir comme contenu d’un Frame (pageFrame).

// Navigate to xaml page
Uri uri = new Uri("/PageContentFile.xaml", UriKind.Relative);
StreamResourceInfo info = Application.GetContentStream(uri);
System.Windows.Markup.XamlReader reader = new System.Windows.Markup.XamlReader();
Page page = (Page)reader.LoadAsync(info.Stream);
this.pageFrame.Content = page;

' Navigate to xaml page
Dim uri As New Uri("/PageContentFile.xaml", UriKind.Relative)
Dim info As StreamResourceInfo = Application.GetContentStream(uri)
Dim reader As New System.Windows.Markup.XamlReader()
Dim page As Page = CType(reader.LoadAsync(info.Stream), Page)
Me.pageFrame.Content = page

Lors de l’appel GetContentStreamStreamvous donne accès, vous devez effectuer le travail supplémentaire de la convertir en type de propriété avec laquelle vous le définirez. Au lieu de cela, vous pouvez laisser WPF s’occuper de l’ouverture et de la conversion du Stream fichier en chargeant un fichier de ressources directement dans la propriété d’un type à l’aide du code.

L’exemple suivant montre comment charger un Page fichier directement dans un Frame (pageFrame) à l’aide de code.

Uri pageUri = new Uri("/PageContentFile.xaml", UriKind.Relative);
this.pageFrame.Source = pageUri;

Dim pageUri As New Uri("/PageContentFile.xaml", UriKind.Relative)
Me.pageFrame.Source = pageUri

L’exemple suivant est l’équivalent sous forme de balisage de l’exemple précédent.

<Frame Name="pageFrame" Source="PageContentFile.xaml" />

Fichiers du site d’origine

Les fichiers de ressources ont une relation explicite avec les assemblys qu’ils sont distribués en même temps que définis par le AssemblyAssociatedContentFileAttribute. Toutefois, vous pouvez être amené à établir une relation implicite ou inexistante entre un assembly et un fichier de données d’application, notamment dans les situations suivantes :

• Un fichier n’existe pas au moment de la compilation.

• Vous ignorez de quels fichiers votre assembly a besoin jusqu’au moment de l’exécution.

• Vous souhaitez pouvoir mettre à jour des fichiers sans recompiler l’assembly auquel ils sont associés.

• Votre application utilise des fichiers de données volumineux, par exemple des fichiers audio et vidéo, et vous souhaitez que les utilisateurs aient le choix de les télécharger ou non.

Il est possible de charger ces types de fichiers à l’aide de schémas d’URI traditionnels, tels que les file:/// schémas et http:// les schémas.

<Image Source="file:///C:/DataFile.bmp" />
<Image Source="http://www.datafilewebsite.com/DataFile.bmp" />

Toutefois, les file:/// schémas et http:// les schémas nécessitent que votre application dispose d’une confiance totale. Si votre application est une application de navigateur XAML (XBAP) lancée à partir d’Internet ou de l’intranet et qu’elle demande uniquement l’ensemble d’autorisations autorisées pour les applications lancées à partir de ces emplacements, les fichiers libres ne peuvent être chargés qu’à partir du site d’origine de l’application (emplacement de lancement). Ces fichiers sont appelés fichiers du site d’origine.

Les fichiers du site d’origine sont la seule option pour les applications partiellement fiables. Toutefois, ils ne se limitent pas à ces applications. Les applications entièrement fiables peuvent tout de même avoir besoin de charger des fichiers de données d’application dont ils n’ont pas connaissance au moment de la génération. Bien que les applications entièrement fiables puissent utiliser file:///, les fichiers de données d’application sont probablement installés dans le même dossier ou sous-dossier que l’assembly d’application. Dans ce cas, l’utilisation du référencement du site d’origine est plus facile que l’utilisation de file:///, car avec file:/// vous devez résoudre le chemin complet du fichier.

Configuration des fichiers du site d’origine

Si votre site d’origine est inexistant ou inconnu au moment de la compilation, vous devez utiliser des mécanismes de déploiement traditionnels pour vous assurer que les fichiers requis sont disponibles au moment de l’exécution, notamment à l’aide du XCopy programme de ligne de commande ou de Microsoft Windows Installer.

Si vous savez au moment de la compilation les fichiers que vous souhaitez trouver sur le site d’origine, mais que vous souhaitez toujours éviter une dépendance explicite, vous pouvez ajouter ces fichiers à un projet MSBuild en tant qu’élément None . Comme pour les fichiers de contenu, vous devez définir l’attribut MSBuild CopyToOutputDirectory pour spécifier que le fichier de site d’origine est copié dans un emplacement relatif à l’assembly généré, en spécifiant la Always valeur ou la PreserveNewest valeur.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ... >  
  ...  
  <None Include="PageSiteOfOriginFile.xaml">  
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>  
  </None>  
  ...  
</Project>  

Lorsque le projet est généré, MSBuild copie les fichiers spécifiés dans le dossier de sortie de build.

Utilisation des fichiers du site d’origine

Pour charger un site de fichier d’origine, vous pouvez appeler la GetRemoteStream méthode de la Application classe, en passant un URI de pack qui identifie le site d’origine souhaité. GetRemoteStream retourne un StreamResourceInfo objet, qui expose le site du fichier d’origine en tant que Stream type de contenu et décrit son type de contenu.

Par exemple, le code suivant montre comment charger GetRemoteStream un Page fichier d’origine de site et le définir comme contenu d’un Frame (pageFrame).

// Navigate to xaml page
Uri uri = new Uri("/SiteOfOriginFile.xaml", UriKind.Relative);
StreamResourceInfo info = Application.GetRemoteStream(uri);
System.Windows.Markup.XamlReader reader = new System.Windows.Markup.XamlReader();
Page page = (Page)reader.LoadAsync(info.Stream);
this.pageFrame.Content = page;

' Navigate to xaml page
Dim uri As New Uri("/SiteOfOriginFile.xaml", UriKind.Relative)
Dim info As StreamResourceInfo = Application.GetRemoteStream(uri)
Dim reader As New System.Windows.Markup.XamlReader()
Dim page As Page = CType(reader.LoadAsync(info.Stream), Page)
Me.pageFrame.Content = page

Lors de l’appel GetRemoteStreamStreamvous donne accès, vous devez effectuer le travail supplémentaire de la convertir en type de propriété avec laquelle vous le définirez. Au lieu de cela, vous pouvez laisser WPF s’occuper de l’ouverture et de la conversion du Stream fichier en chargeant un fichier de ressources directement dans la propriété d’un type à l’aide du code.

L’exemple suivant montre comment charger un Page fichier directement dans un Frame (pageFrame) à l’aide de code.

Uri pageUri = new Uri("pack://siteoforigin:,,,/SiteOfOriginFile.xaml", UriKind.Absolute);
this.pageFrame.Source = pageUri;

Dim pageUri As New Uri("pack://siteoforigin:,,,/Subfolder/SiteOfOriginFile.xaml", UriKind.Absolute)
Me.pageFrame.Source = pageUri

L’exemple suivant est l’équivalent sous forme de balisage de l’exemple précédent.

<Frame Name="pageFrame" Source="pack://siteoforigin:,,,/SiteOfOriginFile.xaml" />

Regénération après changement du type de build

Après avoir changé le type de build d’un fichier de données d’application, vous devez regénérer l’application entière pour vérifier que ces changements sont bien appliqués. Si vous générez uniquement l’application, les changements ne sont pas appliqués.

Voir aussi

• URI à en-tête pack dans WPF