Partager via

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

  • Article

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 tourne autour d’un ensemble spécifique de types de fichiers 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.

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

Une distinction importante à faire entre ces trois types de fichiers est que les fichiers de ressources et de contenu sont connus au moment de la compilation ; un assembly les connaît explicitement. Toutefois, pour les fichiers de site d’origine, un assembly peut n’avoir aucune connaissance de ces fichiers, ou une connaissance implicite par le biais d’une référence URI (Uniform Resource Identifier) de pack ; dans ce dernier cas, il n’y a aucune garantie que le fichier de site d’origine référencé existe bel et bien.

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

Cette rubrique explique 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, la seule façon de garantir la disponibilité consiste à la compiler dans l’assembly exécutable principal d’une application ou l’un de ses assemblys référencés. Ce type de fichier de données d’application est appelé fichier de ressources.

Vous devez utiliser des fichiers de ressources lorsque :

  • Vous n’avez pas besoin de mettre à jour le contenu du fichier de ressources après sa compilation dans un assembly.

  • Vous souhaitez simplifier la complexité de la distribution des applications en réduisant le nombre de 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).

Note

Les fichiers de ressources décrits dans cette section sont différents des fichiers de ressources décrits dans ressources XAML et différents des ressources incorporées ou liées décrites dans Gérer les ressources d’application (.NET).

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>

Note

Dans Visual Studio, vous créez un fichier de ressources en ajoutant un fichier à un projet et en définissant son Build Action sur Resource.

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

Utilisation de fichiers de ressources

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

Par exemple, le code suivant montre comment utiliser GetResourceStream pour charger un fichier de ressources Page 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

Bien que l'appel de GetResourceStream vous donne accès au Stream, vous devez effectuer le travail supplémentaire de le convertir au type de propriété avec laquelle vous l'associerez. Au lieu de cela, vous pouvez laisser WPF s’occuper de l’ouverture et de la conversion du Stream 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 directement dans un Frame (pageFrame) à l’aide du 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 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 propriété Application.StartupUri avec un URI de pack qui 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>

Note

Dans Visual Studio, vous ajoutez un nouveau Window, NavigationWindow, Page, FlowDocumentou ResourceDictionary à un projet, le Build Action du fichier de balisage sera par défaut Page.

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

Note

Si un fichier XAML est configuré en tant qu’élément Resource et n’a pas de fichier code-behind, le code XAML brut est compilé dans un assembly plutôt qu’une version binaire du code XAML brut.

Fichiers de contenu

Un fichier de contenu est distribué en tant que fichier libre en même temps qu’un assembly exécutable. Bien qu’ils ne soient pas compilés dans un assembly, les assemblys sont compilés avec des métadonnées qui établissent une association avec chaque fichier de contenu.

Vous devez utiliser des fichiers de contenu lorsque votre application nécessite un ensemble spécifique de fichiers de données d’application que vous souhaitez 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 de métadonnées CopyToOutputDirectory avec la valeur Always. 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 valeur PreserveNewest.

L’exemple suivant montre un fichier configuré en tant que fichier de contenu copié dans le dossier de sortie de build uniquement lorsqu’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>

Note

Dans Visual Studio, vous créez un fichier de contenu en ajoutant un fichier à un projet et en définissant son Build Action sur Content, et définissez son Copy to Output Directory sur Copy always (identique à Always) et Copy if newer (identique à PreserveNewest).

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

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

La valeur du 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 sont incorporées dans la valeur AssemblyAssociatedContentFileAttribute.

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

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

Utilisation de fichiers de contenu

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

Par exemple, le code suivant montre comment utiliser GetContentStream pour charger un fichier de contenu Page 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

Appeler GetContentStream vous donne accès à Stream, mais vous devez faire le travail supplémentaire de le convertir en type de propriété que vous utiliserez pour le définir. Au lieu de cela, vous pouvez laisser WPF s'occuper de l'ouverture et de la conversion du Stream en chargeant un fichier de ressources directement dans une propriété d'un type via le code.

L’exemple suivant montre comment charger un Page directement dans un Frame (pageFrame) à l’aide du 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 de balisage de l’exemple précédent.

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

Fichiers de site d’origine

Les fichiers de ressources ont une relation explicite avec les assemblages avec lesquels ils sont distribués, telle que définie par le AssemblyAssociatedContentFileAttribute. Toutefois, il peut arriver que vous souhaitiez établir une relation implicite ou inexistante entre un assembly et un fichier de données d’application, notamment quand :

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

  • Vous ne savez pas quels fichiers votre assembly nécessiteront 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, tels que l’audio et la vidéo, et vous souhaitez uniquement que les utilisateurs les téléchargent s’ils choisissent de les télécharger.

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

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

Toutefois, les schémas file:/// et http:// 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 site d’origine.

Les fichiers de site d’origine sont la seule option pour les applications d’approbation partielle, même si elles ne sont pas limitées aux applications d’approbation partielle. Les applications de confiance totale peuvent toujours avoir besoin de charger des fichiers de données d’application qu’ils ne connaissent pas au moment de la génération ; bien que les applications de confiance totale puissent utiliser file:///, il est probable que les fichiers de données d’application soient installés dans le même dossier que, ou un sous-dossier de l’assembly d’application. Dans ce cas, l’utilisation du référencement de site d’origine est plus facile que l’utilisation de file:///, car l’utilisation de file:/// vous oblige à utiliser le chemin complet du fichier.

Note

Les fichiers de site d’origine ne sont pas mis en cache avec une application de navigateur XAML (XBAP) sur une machine cliente, tandis que les fichiers de contenu sont. Par conséquent, ils sont téléchargés uniquement lorsqu’ils sont spécifiquement demandés. Si une application de navigateur XAML (XBAP) a des fichiers multimédias volumineux, la configuration de ces fichiers en tant que fichiers de site d’origine signifie que le lancement initial de l’application est beaucoup plus rapide et que les fichiers ne sont téléchargés qu’à la demande.

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 programme de ligne de commande XCopy 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 site du fichier d’origine est copié à un emplacement relatif à l’assembly généré, en spécifiant la valeur Always ou la valeur PreserveNewest.

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

Note

Dans Visual Studio, vous créez un fichier de site d’origine en ajoutant un fichier à un projet et en définissant son Build Action sur None.

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

Utilisation de fichiers du site d'origine

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

Par exemple, le code suivant montre comment utiliser GetRemoteStream pour charger un fichier d’origine Page 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

Appeler GetRemoteStream vous donne accès au Stream, mais vous devez effectuer le travail supplémentaire de le convertir au type de la propriété dans laquelle vous allez le définir. Au lieu de cela, vous pouvez laisser WPF s'occuper de l'ouverture et de la conversion du Stream en chargeant un fichier de ressources directement dans la propriété d'un type en utilisant le code.

L’exemple suivant montre comment charger un Page directement dans un Frame (pageFrame) à l’aide du 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 de balisage de l’exemple précédent.

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

Reconstruction après modification du type de build

Après avoir modifié le type de build d’un fichier de données d’application, vous devez reconstruire l’ensemble de l’application pour vous assurer que ces modifications sont appliquées. Si vous générez uniquement l’application, les modifications ne sont pas appliquées.

Voir aussi