WPF-programresurs, innehåll och datafiler

Microsoft Windows-program är ofta beroende av filer som innehåller icke-körbara data, till exempel XAML (Extensible Application Markup Language), bilder, video och ljud. Windows Presentation Foundation (WPF) har särskilt stöd för att konfigurera, identifiera och använda dessa typer av datafiler, som kallas programdatafiler. Det här stödet kretsar kring en specifik uppsättning programdatafiltyper, inklusive:

• Resource Files: Datafiler som kompileras till antingen en körbar eller biblioteks-WPF-sammansättning.

• Content Files: Fristående datafiler som har en explicit koppling till en körbar WPF-sammansättning.

• Site of Origin Files: Fristående datafiler som inte har någon koppling till en körbar WPF-sammansättning.

En viktig skillnad mellan dessa tre typer av filer är att resursfiler och innehållsfiler är kända vid bygget. en sammansättning har uttrycklig kunskap om dem. För ursprungsfiler kan dock en sammansättning inte ha någon kunskap om dem alls, eller implicit kunskap via en URI-referens (uniform resource identifier). i det senare fallet finns det ingen garanti för att den refererade ursprungsfilen faktiskt finns.

För att referera till programdatafiler använder Windows Presentation Foundation (WPF) URI-schemat (Pack Uniform Resource Identifier), som beskrivs i detalj i Pack-URI:er i WPF).

I det här avsnittet beskrivs hur du konfigurerar och använder programdatafiler.

Resursfiler

Om en programdatafil alltid måste vara tillgänglig för ett program är det enda sättet att garantera tillgänglighet att kompilera den till ett programs huvudsakliga körbara sammansättning eller någon av dess refererade sammansättningar. Den här typen av programdatafil kallas för en resursfil.

Du bör använda resursfiler när:

• Du behöver inte uppdatera resursfilens innehåll när den har kompilerats till en sammansättning.

• Du vill förenkla programdistributionens komplexitet genom att minska antalet filberoenden.

• Ditt programdatadokument måste vara anpassningsbart för lokalisering (se WPF Globalization and Localization Overview).

Konfigurera resursfiler

I WPF är en resursfil en fil som ingår i ett MsBuild-projekt (Microsoft Build Engine) som ett Resource objekt.

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

När projektet skapas kompilerar MSBuild resursen till sammansättningen.

Använda resursfiler

Om du vill läsa in en resursfil kan du anropa GetResourceStream-metoden för klassen Application och skicka en paket-URI som identifierar önskad resursfil. GetResourceStream returnerar ett StreamResourceInfo objekt som exponerar resursfilen som en Stream och beskriver dess innehållstyp.

I följande kod visas till exempel hur du använder GetResourceStream för att läsa in en Page resursfil och ange den som innehållet i en 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

När du anropar GetResourceStream får du åtkomst till Stream, men du måste utföra det ytterligare arbetet med att konvertera det till den typ av egenskap som du kommer att använda den med. I stället kan du låta WPF ta hand om att öppna och konvertera Stream genom att läsa in en resursfil direkt i egenskapen för en typ med hjälp av kod.

I följande exempel visas hur du läser in en Page direkt i en Frame (pageFrame) med hjälp av kod.

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

Följande exempel är motsvarigheten till märkningen från det föregående exemplet.

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

Programkodfiler som resursfiler

En särskild uppsättning WPF-programkodfiler kan refereras med hjälp av paket-URI:er, inklusive fönster, sidor, flödesdokument och resursordlistor. Du kan till exempel ange egenskapen Application.StartupUri med en pack-URI som refererar till fönstret eller sidan som du vill läsa in när ett program startar.

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

Du kan göra detta när en XAML-fil ingår i ett MSBuild-projekt som ett Page objekt.

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

När ett projekt med Page objekt kompileras konverteras XAML-objekten till binärt format och kompileras till den associerade sammansättningen. Dessa filer kan därför användas på samma sätt som vanliga resursfiler.

Innehållsfiler

En innehållsfil distribueras som en lös fil tillsammans med en körbar sammansättning. Även om de inte kompileras till en sammansättning kompileras sammansättningar med metadata som upprättar en association med varje innehållsfil.

Du bör använda innehållsfiler när programmet kräver en specifik uppsättning programdatafiler som du vill kunna uppdatera utan att kompilera om sammansättningen som använder dem.

Konfigurera innehållsfiler

Om du vill lägga till en innehållsfil i ett projekt måste en programdatafil inkluderas som ett Content objekt. Eftersom en innehållsfil inte kompileras direkt till sammansättningen måste du dessutom ange metadataelementet MSBuild CopyToOutputDirectory för att ange att innehållsfilen kopieras till en plats som är relativ till den byggda sammansättningen. Om du vill att resursen ska kopieras till byggutdatamappen varje gång ett projekt byggs anger du metadataelementet CopyToOutputDirectory med värdet Always. Annars kan du se till att endast den senaste versionen av resursen kopieras till utdatamappen för bygget med hjälp av värdet PreserveNewest.

Följande visar en fil som är konfigurerad som en innehållsfil som kopieras till utdatamappen för bygget endast när en ny version av resursen läggs till i projektet.

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

När projektet skapas kompileras ett AssemblyAssociatedContentFileAttribute-attribut till sammansättningsmetadata för varje innehållsfil.

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

Värdet för AssemblyAssociatedContentFileAttribute innebär sökvägen till innehållsfilen i förhållande till dess position i projektet. Om en innehållsfil till exempel finns i en projektundermapp skulle den ytterligare sökvägsinformationen införlivas i värdet AssemblyAssociatedContentFileAttribute.

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

Värdet AssemblyAssociatedContentFileAttribute är också värdet för sökvägen till innehållsfilen i build-utmatningsmappen.

Använda innehållsfiler

Om du vill läsa in en innehållsfil kan du anropa GetContentStream-metoden för klassen Application och skicka en paket-URI som identifierar önskad innehållsfil. GetContentStream returnerar ett StreamResourceInfo objekt som exponerar innehållsfilen som en Stream och beskriver dess innehållstyp.

I följande kod visas till exempel hur du använder GetContentStream för att läsa in en Page innehållsfil och ange den som innehållet i en 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

När du anropar GetContentStream får du åtkomst till Stream, men du måste utföra det ytterligare arbetet med att konvertera det till den typ av egenskap som du kommer att använda den med. I stället kan du låta WPF ta hand om att öppna och konvertera Stream genom att läsa in en resursfil direkt i egenskapen för en typ med hjälp av kod.

I följande exempel visas hur du läser in en Page direkt i en Frame (pageFrame) med hjälp av kod.

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

Följande exempel är motsvarigheten till märkningen från det föregående exemplet.

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

Plats för ursprungsfiler

Resursfiler har en explicit relation till de sammansättningar som de distribueras tillsammans med, enligt definitionen i AssemblyAssociatedContentFileAttribute. Det finns dock tillfällen då du kanske vill upprätta en implicit eller obefintlig relation mellan en sammansättning och en programdatafil, inklusive när:

• En fil finns inte vid kompileringstillfället.

• Du vet inte vilka filer din assembly kommer att kräva förrän vid körning.

• Du vill kunna uppdatera filer utan att kompilera om sammansättningen som de är associerade med.

• Ditt program använder stora datafiler, till exempel ljud och video, och du vill bara att användarna ska ladda ned dem om de väljer att göra det.

Det går att läsa in dessa typer av filer med hjälp av traditionella URI-scheman, till exempel file:///- och http://-scheman.

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

Men scheman för file:/// och http:// kräver att din applikation har fullständig tillit. Om ditt program är ett XAML-webbläsarprogram (XBAP) som startades från Internet eller intranätet, och det endast begär den uppsättning behörigheter som tillåts för program som startas från dessa platser, kan lösa filer bara läsas in från programmets ursprungsplats (startplats). Sådana filer kallas ursprungsplats filer.

Ursprungsplatsfiler är det enda alternativet för program med partiellt förtroende, men de är inte begränsade till sådana program. Program med fullständigt förtroende kan fortfarande behöva läsa in programdatafiler som de inte känner till vid bygget. även om program med fullständigt förtroende kan använda file:///, är det troligt att programdatafilerna installeras i samma mapp som eller en undermapp för programsammansättningen. I det här fallet är det enklare att använda referenser till ursprunget än att använda file:///, eftersom användning av file:/// kräver att du tar fram den fullständiga sökvägen till filen.

Konfigurera plats för ursprungsfiler

Om dina ursprungsfiler är obefintliga eller okända vid kompilering måste du använda traditionella distributionsmekanismer för att säkerställa att de nödvändiga filerna är tillgängliga vid körtid, vilket inkluderar användning av kommandoradsprogrammet XCopy eller Microsoft Windows Installer.

Om du vid kompileringstillfället vet vilka filer som du vill ska finnas på ursprungsplatsen, men ändå vill undvika ett explicit beroende, kan du lägga till filerna i ett MSBuild-projekt som None objekt. Precis som med innehållsfiler måste du ange attributet MSBuild CopyToOutputDirectory för att ange att ursprungsplatsens fil kopieras till en plats som är relativ till den byggda sammansättningen genom att ange antingen värdet Always eller PreserveNewest värde.

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

När projektet har skapats kopierar MSBuild de angivna filerna till utdatamappen för bygget.

Använda ursprungsplatsspecifika filer

Om du vill läsa in en ursprungsfil kan du anropa GetRemoteStream-metoden för klassen Application och skicka en paket-URI som identifierar den önskade ursprungsfilen. GetRemoteStream returnerar ett StreamResourceInfo objekt som exponerar ursprungsfilen som en Stream och beskriver dess innehållstyp.

Ett exempel är följande kod, som visar hur du använder GetRemoteStream för att läsa in en ursprungsfil från Page och ange den som innehållet i en 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

När du anropar GetRemoteStream får du åtkomst till Stream, men du måste utföra det ytterligare arbetet med att konvertera det till den typ av egenskap som du kommer att använda den med. I stället kan du låta WPF ta hand om att öppna och konvertera Stream genom att läsa in en resursfil direkt i egenskapen för en typ med hjälp av kod.

I följande exempel visas hur du läser in en Page direkt i en Frame (pageFrame) med hjälp av kod.

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

Följande exempel är motsvarigheten till märkningen från det föregående exemplet.

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

Ombyggnad efter ändring av byggtyp

När du har ändrat byggtypen för en programdatafil måste du återskapa hela programmet för att säkerställa att ändringarna tillämpas. Om du bara skapar programmet tillämpas inte ändringarna.

Se även

• Pack-URI:er i WPF