Delen via

WPF-toepassingsresource, inhoud en gegevensbestanden

Microsoft Windows-toepassingen zijn vaak afhankelijk van bestanden die niet-uitvoerbare gegevens bevatten, zoals Extensible Application Markup Language (XAML), afbeeldingen, video en audio. Windows Presentation Foundation (WPF) biedt speciale ondersteuning voor het configureren, identificeren en gebruiken van deze typen gegevensbestanden, die toepassingsgegevensbestanden worden genoemd. Deze ondersteuning draait om een specifieke set toepassingsgegevensbestandstypen, waaronder:

  • Resourcebestanden: Gegevensbestanden die zijn gecompileerd in een uitvoerbare of bibliotheek WPF-assembly.

  • Inhoudsbestanden: zelfstandige gegevensbestanden die een expliciete koppeling hebben met een uitvoerbare WPF-assembly.

  • Site of Origin Files: zelfstandige gegevensbestanden die geen koppeling hebben met een uitvoerbare WPF-assembly.

Een belangrijk onderscheid tussen deze drie typen bestanden is dat resourcebestanden en inhoudsbestanden bekend zijn tijdens het bouwen; een assembly beschikt over expliciete kennis ervan. Voor bestanden van de oorsprongssite heeft een assembly echter helemaal geen kennis of alleen impliciete kennis via een URI-verwijzing (Uniform Resource Identifier) van een pakket; in dit laatste geval, is er geen garantie dat de verwezen oorsprongssitebestanden daadwerkelijk bestaan.

Als u wilt verwijzen naar gegevensbestanden van toepassingen, maakt Windows Presentation Foundation (WPF) gebruik van het URI-schema (Pack Uniform Resource Identifier), dat gedetailleerd wordt beschreven in Pack-URI's in WPF-).

In dit onderwerp wordt beschreven hoe u gegevensbestanden van toepassingen configureert en gebruikt.

Resourcebestanden

Als een toepassingsgegevensbestand altijd beschikbaar moet zijn voor een toepassing, is de enige manier om de beschikbaarheid te garanderen door het te compileren in de belangrijkste uitvoerbare assembly van een toepassing of een van de bijbehorende assembly's waarnaar wordt verwezen. Dit type toepassingsgegevensbestand wordt een resourcebestandgenoemd.

U moet resourcebestanden gebruiken wanneer:

  • U hoeft de inhoud van het resourcebestand niet bij te werken nadat het is gecompileerd in een assembly.

  • U wilt de complexiteit van toepassingsdistributie vereenvoudigen door het aantal bestandsafhankelijkheden te verminderen.

  • Uw toepassingsgegevensbestand moet kunnen worden gelokaliseerd (zie WPF Globalization and Localization Overview).

Opmerking

De resourcebestanden die in deze sectie worden beschreven, verschillen van de resourcebestanden die worden beschreven in XAML-resources en verschillen van de ingesloten of gekoppelde resources die worden beschreven in Application Resources (.NET) beheren.

Resourcebestanden configureren

In WPF is een resourcebestand een bestand dat is opgenomen in een Microsoft build engine -project (MSBuild) als een Resource item.

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

Opmerking

In Visual Studio maakt u een resourcebestand door een bestand toe te voegen aan een project en de bijbehorende Build Action in te stellen op Resource.

Wanneer het project is gebouwd, compileert MSBuild de resource in de assembly.

Resourcebestanden gebruiken

Als u een resourcebestand wilt laden, kunt u de GetResourceStream methode van de Application-klasse aanroepen, waarbij een pakket-URI wordt doorgegeven die het gewenste resourcebestand identificeert. GetResourceStream retourneert een StreamResourceInfo-object, dat het resourcebestand beschikbaar maakt als een Stream en het inhoudstype beschrijft.

In de volgende code ziet u bijvoorbeeld hoe u GetResourceStream gebruikt om een Page resourcebestand te laden en dit in te stellen als de inhoud van een 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

Bij het aanroepen van GetResourceStream krijgt u toegang tot de Stream, maar moet u het extra werk doen om deze te converteren naar het type van de eigenschap waarmee u deze instelt. In plaats daarvan kunt u WPF de Stream laten openen en converteren door een resourcebestand rechtstreeks te laden in de eigenschap van een type met behulp van code.

In het volgende voorbeeld ziet u hoe u een Page rechtstreeks in een Frame (pageFrame) laadt met behulp van 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

Het volgende voorbeeld is het equivalent van de opmaak van het voorgaande voorbeeld.

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

Applicatiecodebestanden als resourcebestanden

Er kan naar een speciale set WPF-toepassingscodebestanden worden verwezen met behulp van pack-URI's, waaronder vensters, pagina's, stroomdocumenten en resourcewoordenlijsten. U kunt bijvoorbeeld de eigenschap Application.StartupUri instellen met een pack-URI die verwijst naar het venster of de pagina die u wilt laden wanneer een toepassing wordt gestart.

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

U kunt dit doen wanneer een XAML-bestand is opgenomen in een MSBuild-project als een Page item.

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

Opmerking

In Visual Studio voegt u een nieuwe Window, NavigationWindow, Page, FlowDocumentof ResourceDictionary toe aan een project. De Build Action voor het opmaakbestand wordt standaard Page.

Wanneer een project met Page items wordt gecompileerd, worden de XAML-items geconverteerd naar binaire indeling en gecompileerd in de bijbehorende assembly. Daarom kunnen deze bestanden op dezelfde manier worden gebruikt als typische bronbestanden.

Opmerking

Als een XAML-bestand is geconfigureerd als een Resource-item en geen code-behind-bestand heeft, wordt de onbewerkte XAML gecompileerd in een assembly in plaats van een binaire versie van de onbewerkte XAML.

Inhoudsbestanden

Een inhoudsbestand wordt gedistribueerd als een los bestand naast een uitvoerbare assembly. Hoewel ze niet in een assembly worden gecompileerd, worden assembly's gecompileerd met metagegevens die een koppeling tot stand brengen met elk inhoudsbestand.

U moet inhoudsbestanden gebruiken wanneer uw toepassing een specifieke set toepassingsgegevensbestanden vereist die u wilt kunnen bijwerken zonder de assembly opnieuw te compileren die ze verbruikt.

Inhoudsbestanden configureren

Als u een inhoudsbestand aan een project wilt toevoegen, moet een toepassingsgegevensbestand worden opgenomen als een Content item. Bovendien moet u, omdat een inhoudsbestand niet rechtstreeks in de assembly is gecompileerd, het element MSBuild CopyToOutputDirectory metagegevens instellen om op te geven dat het inhoudsbestand wordt gekopieerd naar een locatie die relatief is ten opzichte van de ingebouwde assembly. Als u wilt dat de resource elke keer dat een project wordt gebouwd naar de outputmap van de build wordt gekopieerd, stelt u het metadata-element CopyToOutputDirectory in met de waarde Always. Anders kunt u ervoor zorgen dat alleen de nieuwste versie van de resource wordt gekopieerd naar de uitvoermap van de build met behulp van de PreserveNewest waarde.

Hieronder ziet u een bestand dat is geconfigureerd als een inhoudsbestand dat alleen naar de uitvoermap van de build wordt gekopieerd wanneer er een nieuwe versie van de resource aan het project wordt toegevoegd.

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

Opmerking

In Visual Studio maakt u een inhoudsbestand door een bestand toe te voegen aan een project en de bijbehorende Build Action in te stellen op Contenten de bijbehorende Copy to Output Directory in te stellen op Copy always (hetzelfde als Always) en Copy if newer (hetzelfde als PreserveNewest).

Wanneer het project is gebouwd, wordt een AssemblyAssociatedContentFileAttribute kenmerk gecompileerd in de metagegevens van de assembly voor elk inhoudsbestand.

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

De waarde van de AssemblyAssociatedContentFileAttribute impliceert het pad naar het inhoudsbestand ten opzichte van de positie in het project. Als een inhoudsbestand zich bijvoorbeeld in een projectsubmap bevindt, wordt de aanvullende padinformatie opgenomen in de AssemblyAssociatedContentFileAttribute waarde.

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

De AssemblyAssociatedContentFileAttribute waarde is ook de waarde van het pad naar het inhoudsbestand in de uitvoermap van de build.

Inhoudsbestanden gebruiken

Als u een inhoudsbestand wilt laden, kunt u de GetContentStream methode van de klasse Application aanroepen, waarbij een pakket-URI wordt doorgegeven waarmee het gewenste inhoudsbestand wordt geïdentificeerd. GetContentStream retourneert een StreamResourceInfo-object, dat het inhoudsbestand beschikbaar maakt als een Stream en het inhoudstype beschrijft.

In de volgende code ziet u hoe u GetContentStream gebruikt om een Page inhoudsbestand te laden en in te stellen als de inhoud van een 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

Bij het aanroepen van GetContentStream krijgt u toegang tot de Stream, maar moet u het extra werk doen om deze te converteren naar het type van de eigenschap waarmee u deze instelt. In plaats daarvan kunt u WPF de Stream laten openen en converteren door een resourcebestand rechtstreeks te laden in de eigenschap van een type met behulp van code.

In het volgende voorbeeld ziet u hoe u een Page rechtstreeks in een Frame (pageFrame) laadt met behulp van 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

Het volgende voorbeeld is het equivalent van de opmaak van het voorgaande voorbeeld.

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

Site van oorsprongsbestanden

Resourcebestanden hebben een expliciete relatie met de assemblages waarmee ze worden gedistribueerd, zoals gedefinieerd door de AssemblyAssociatedContentFileAttribute. Er zijn echter momenten waarop u mogelijk een impliciete of niet-bestaande relatie tot stand wilt brengen tussen een assembly en een toepassingsgegevensbestand, waaronder wanneer:

  • Er bestaat geen bestand tijdens het compileren.

  • U weet niet welke bestanden uw assembly nodig heeft tot de runtime.

  • U wilt bestanden kunnen bijwerken zonder de assembly waaraan ze zijn gekoppeld, opnieuw te compileren.

  • Uw toepassing maakt gebruik van grote gegevensbestanden, zoals audio en video, en u wilt alleen dat gebruikers ze downloaden als ze ervoor kiezen.

Het is mogelijk om deze typen bestanden te laden met behulp van traditionele URI-schema's, zoals de file:/// en http:// schema's.

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

Voor de file:///- en http://-schema's moet uw toepassing echter volledige vertrouwen hebben. Als uw toepassing een XAML-browsertoepassing (XBAP) is die is gestart vanaf internet of intranet en alleen de set machtigingen aanvraagt die zijn toegestaan voor toepassingen die vanaf die locaties worden gestart, kunnen losse bestanden alleen worden geladen vanaf de oorspronkelijke locatie van de toepassing (startlocatie). Dergelijke bestanden worden site van oorsprong bestanden genoemd.

Site-of-origin-bestanden zijn de enige optie voor gedeeltelijke vertrouwenstoepassingen, hoewel ze niet beperkt zijn tot toepassingen met gedeeltelijke vertrouwensrelaties. Toepassingen met volledig vertrouwen moeten mogelijk nog steeds toepassingsgegevensbestanden laden die ze niet kennen tijdens de build; hoewel toepassingen met volledig vertrouwen file:/// kunnen gebruiken, is het waarschijnlijk dat de toepassingsgegevensbestanden worden geïnstalleerd in dezelfde map als, of een submap van, de toepassingsassembly. In dit geval is het gebruik van de site van oorsprong waarnaar wordt verwezen eenvoudiger dan het gebruik van file:///, omdat u met file:/// het volledige pad van het bestand moet voltooien.

Opmerking

Site-of-origin-bestanden worden niet in de cache opgeslagen in een XAML-browsertoepassing (XBAP) op een clientcomputer, terwijl inhoudsbestanden wel zijn. Daarom worden ze alleen gedownload wanneer ze specifiek worden aangevraagd. Als een XBAP-toepassing (XAML-browsertoepassing) grote mediabestanden bevat, betekent het configureren als site van oorsprongsbestanden dat het starten van de eerste toepassing veel sneller is en dat de bestanden alleen op aanvraag worden gedownload.

Site van oorsprongsbestanden configureren

Als uw site met oorspronkelijke bestanden niet bestaat of onbekend is tijdens het compileren, moet u traditionele implementatiemechanismen gebruiken om ervoor te zorgen dat de vereiste bestanden beschikbaar zijn tijdens runtime, waaronder het gebruik van het XCopy opdrachtregelprogramma of microsoft Windows Installer.

Als u op het moment van compileren de bestanden kent die u op de site van oorsprong wilt bevinden, maar toch een expliciete afhankelijkheid wilt voorkomen, kunt u deze bestanden toevoegen aan een MSBuild-project als None item. Net als bij inhoudsbestanden moet u het kenmerk MSBuild CopyToOutputDirectory instellen om op te geven dat de site van het oorspronkelijke bestand wordt gekopieerd naar een locatie die ten opzichte van de ingebouwde assembly is, door de Always waarde of de PreserveNewest-waarde op te geven.

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

Opmerking

In Visual Studio maakt u een oorsprongsbestandslocatie door een bestand toe te voegen aan een project en de bijbehorende Build Action in te stellen op None.

Wanneer het project is gebouwd, kopieert MSBuild de opgegeven bestanden naar de build-uitvoermap.

Site of Origin Files gebruiken

Als u een site van oorsprongsbestand wilt laden, kunt u de GetRemoteStream methode van de Application-klasse aanroepen, waarbij een pack-URI wordt doorgegeven die de gewenste site van het oorspronkelijke bestand identificeert. GetRemoteStream retourneert een StreamResourceInfo-object, waarmee de site van het oorspronkelijke bestand als een Stream wordt weergegeven en het inhoudstype wordt beschreven.

In de volgende code ziet u bijvoorbeeld hoe u GetRemoteStream gebruikt om een Page site van oorsprongsbestand te laden en deze in te stellen als de inhoud van een 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

Bij het aanroepen van GetRemoteStream krijgt u toegang tot de Stream, maar moet u het extra werk doen om deze te converteren naar het type van de eigenschap waarmee u deze instelt. In plaats daarvan kunt u WPF de Stream laten openen en converteren door een resourcebestand rechtstreeks te laden in de eigenschap van een type met behulp van code.

In het volgende voorbeeld ziet u hoe u een Page rechtstreeks in een Frame (pageFrame) laadt met behulp van 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

Het volgende voorbeeld is het equivalent van de opmaak van het voorgaande voorbeeld.

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

Herbouwen na het wijzigen van het buildtype

Nadat u het buildtype van een toepassingsgegevensbestand hebt gewijzigd, moet u de hele toepassing opnieuw bouwen om ervoor te zorgen dat deze wijzigingen worden toegepast. Als u de toepassing alleen bouwt, worden de wijzigingen niet toegepast.

Zie ook

  • Last updated on