Condividi tramite

URI di pacchetto in WPF

  • Articolo

In Windows Presentation Foundation (WPF), gli URI (Uniform Resource Identifier) vengono usati per identificare e caricare i file in molti modi, tra cui:

  • Specificare l'interfaccia utente da mostrare all'avvio di un'applicazione.

  • Caricamento di immagini.

  • Navigazione verso le pagine

  • Caricamento di file di dati non eseguibili.

Inoltre, gli URI possono essere usati per identificare e caricare file da diverse posizioni, tra cui:

  • L'assemblea attuale.

  • Assembly a cui si fa riferimento.

  • Posizione relativa a un assemblaggio.

  • Sito dell'applicazione di origine.

Per fornire un meccanismo coerente per identificare e caricare questi tipi di file da questi percorsi, WPF sfrutta l'estendibilità dello schema URI pack . Questo argomento offre una panoramica dello schema, illustra come costruire URI di tipo pack per diversi scenari, illustra gli URI assoluti e relativi e la risoluzione degli URI, prima di illustrare come usare gli URI di tipo pack sia dal markup che dal codice.

Schema Pack URI

Lo schema URI di tipo 'pack' viene usato dalla specifica delle Open Packaging Conventions (OPC), che descrive un modello per organizzare e identificare i contenuti. Gli elementi chiave di questo modello sono pacchetti e parti, in cui un pacchetto è un contenitore logico per una o più parti logiche . La figura seguente illustra questo concetto.

diagramma dei pacchetti e delle parti

Per identificare le parti, la specifica OPC sfrutta l'estendibilità di RFC 2396 (Uniform Resource Identifiers (URI): Sintassi generica) per definire lo schema URI del pacchetto.

Lo schema specificato da un URI è definito dal prefisso; http, ftp e file sono esempi noti. Lo schema URI pack usa "pack" come schema e contiene due componenti: authority e path. Di seguito è riportato il formato per un URI di tipo pack.

pack://autorità/percorso

L'autorità specifica il tipo di pacchetto contenuto in una parte, mentre il percorso specifica la posizione di una parte all'interno di un pacchetto.

Questo concetto è illustrato nella figura seguente:

Relazione tra pacchetti, autorità e percorso

I pacchetti e le parti sono analoghi alle applicazioni e ai file, in cui un'applicazione (pacchetto) può includere uno o più file (parti), tra cui:

  • File di risorse compilati nell'assembly locale.

  • File di risorse compilati in un assembly di riferimento.

  • File di risorse compilati in un assembly di riferimento.

  • File di contenuto.

  • File del sito di origine.

Per accedere a questi tipi di file, WPF supporta due autorità: application:/// e siteoforigin:///. L'autorità di application:/// identifica i file di dati dell'applicazione noti in fase di compilazione, inclusi i file di risorse e contenuto. L'autorità di siteoforigin:/// identifica il sito dei file di origine. L'ambito di ogni autorità è illustrato nella figura seguente.

diagramma URI del pacchetto

Nota

Il componente dell'autorità di un URI pack è un URI incorporato che punta a un pacchetto e deve essere conforme a RFC 2396. Inoltre, il carattere "/" deve essere sostituito con il carattere "," e i caratteri riservati, come "%" e "?", devono essere scappati. Per informazioni dettagliate, vedere OPC.

Le sezioni seguenti illustrano come costruire URI di tipo pack usando queste due autorità in combinazione con i percorsi appropriati per identificare i file di risorse, contenuto e sito di origine.

URI del pacchetto di file risorsa

I file di risorse vengono configurati come elementi di msbuild Resource e vengono compilati in assembly. WPF supporta la costruzione di URI di tipo pack che possono essere usati per identificare i file di risorse compilati nell'assembly locale o compilati in un assembly a cui viene fatto riferimento dall'assembly locale.

File di risorse dell'assembly locale

L'URI pack per un file di risorse compilato nell'assembly locale usa l'autorità e il percorso seguenti:

  • Autorità: application:///.

  • Percorso: nome del file di risorse, incluso il relativo percorso, rispetto alla radice della cartella del progetto assembly locale.

L'esempio seguente mostra l'URI pack per un file di risorse XAML che si trova nella radice della cartella del progetto dell'assembly locale.

pack://application:,,,/ResourceFile.xaml

L'esempio seguente mostra il pack URI per un file XAML di risorse che si trova in una sottocartella della cartella del progetto dell'assembly locale.

pack://application:,,,/Subfolder/ResourceFile.xaml

File di risorse dell'assembly a cui si fa riferimento

L'URI pack per un file di risorse compilato in un assembly a cui viene fatto riferimento usa l'autorità e il percorso seguenti:

  • Autorità: application:///.

  • Percorso: Il nome di un file di risorse compilato in un assembly di riferimento. Il percorso deve essere conforme al formato seguente:

    AssemblyShortName{; Versione]{;PublicKey]; component/Path

    • AssemblyShortName: nome breve dell'assembly di riferimento.

    • ; Versione [facoltativo]: versione dell'assembly a cui si fa riferimento che contiene il file di risorse. Viene usato quando vengono caricati due o più assembly a cui si fa riferimento con lo stesso nome breve.

    • ;PublicKey [facoltativo]: la chiave pubblica utilizzata per firmare l'assembly di riferimento. Viene usato quando vengono caricati due o più assembly a cui si fa riferimento con lo stesso nome breve.

    • ; componente: specifica che l'assembly a cui si fa riferimento è quello locale.

    • /Path: nome del file di risorse, incluso il relativo percorso, relativo alla radice della cartella del progetto dell'assembly a cui si fa riferimento.

L'esempio seguente mostra il "pack URI" per un file di risorse XAML che si trova nella cartella radice del progetto dell'assembly di riferimento.

pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml

L'esempio seguente mostra il pack URI per un file di risorse XAML che si trova in una sottocartella della cartella del progetto dell'assembly di riferimento.

pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml

L'esempio seguente mostra l'URI pack per un file di risorse XAML che si trova nella cartella radice di una cartella di progetto specifica della versione di un assembly a cui viene fatto riferimento.

pack://application:,,,/ReferencedAssembly;v1.0.0.1;component/ResourceFile.xaml

Nota che la sintassi dell'URI pack per i file di risorse dell'assembly a cui si fa riferimento può essere usata solo con l'autorità application:///. Ad esempio, il codice seguente non è supportato in WPF.

pack://siteoforigin:,,,/SomeAssembly;component/ResourceFile.xaml

URI del pacchetto di file di contenuto

L'URI pack per un file di contenuti utilizza la seguente autorità e percorso:

  • Autorità: application:///.

  • Percorso: nome del file di contenuto, incluso il percorso relativo al percorso del file system dell'assembly eseguibile principale dell'applicazione.

L'esempio seguente mostra un pack URI per un file di contenuto XAML, situato nella stessa cartella dell'assembly eseguibile.

pack://application:,,,/ContentFile.xaml

L'esempio seguente mostra l'URI pack per un file di contenuto XAML situato in una sottocartella relativa all'assembly eseguibile dell'applicazione.

pack://application:,,,/Subfolder/ContentFile.xaml

Nota

Impossibile passare ai file di contenuto HTML. Lo schema URI supporta solo lo spostamento ai file HTML che si trovano nel sito di origine.

URI del sito di origine del pacchetto

L'URI pack per un file di origine del sito utilizza l'autorità e il percorso seguenti:

  • Autorità: siteoforigin:///.

  • Percorso: nome del file di origine, incluso il percorso relativo alla posizione da cui è stato avviato l'assembly eseguibile.

L'esempio seguente mostra l'URI pack per un file XAML del sito di origine, archiviato nella posizione da cui è avviato l'assembly eseguibile.

pack://siteoforigin:,,,/SiteOfOriginFile.xaml

L'esempio seguente mostra l'URI del pack per un file XAML di origine del sito archiviato in una sottocartella relativa al percorso da cui viene lanciato l'assembly eseguibile dell'applicazione.

pack://siteoforigin:,,,/Subfolder/SiteOfOriginFile.xaml

File della pagina

I file XAML configurati come elementi di MSBuild Page vengono compilati in assembly nello stesso modo dei file di risorse. Di conseguenza, è possibile identificare gli elementi di MSBuild Page usando gli URI pack per i file di risorse.

I tipi di file XAML comunemente configurati come elementi di MSBuildPage hanno uno dei seguenti elementi come elemento radice:

URI assoluti e relativi del pacchetto

Un URI di pacchetto completamente qualificato include lo schema, l'autorità e il percorso ed è considerato un URI pack assoluto. Come semplificazione per gli sviluppatori, gli elementi XAML in genere consentono di impostare gli attributi appropriati con un URI pack relativo, che include solo il percorso.

Considera, ad esempio, il seguente URI assoluto di pacchetto per un file di risorse nell'assembly locale.

pack://application:,,,/ResourceFile.xaml

L'URI pack relativo che fa riferimento a questo file di risorse sarà il seguente.

/ResourceFile.xaml

Nota

Poiché i file del sito di origine non sono associati agli assembly, è possibile fare riferimento solo agli URI assoluti del pacchetto.

Per impostazione predefinita, un URI pack relativo viene considerato relativo alla posizione del markup o del codice che contiene il riferimento. Se viene utilizzata una barra rovesciata iniziale, tuttavia, il riferimento URI relativo al pacchetto viene considerato relativo alla radice dell'applicazione. Si consideri ad esempio la struttura di progetto seguente.

App.xaml

Page2.xaml

\SubFolder

+ Page1.xaml

+ Page2.xaml

Se Page1.xaml contiene un URI che fa riferimento a: Root\SubFolder\Page2.xaml, il riferimento può utilizzare il seguente URI relativo del pacchetto.

Page2.xaml

Se Page1.xaml contiene un URI che fa riferimento a Root\Page2.xaml, il riferimento può utilizzare il seguente URI relativo del pacchetto.

/Page2.xaml

Risoluzione URI Pack

Il formato degli URI di tipo pack consente agli URI di tipo pack di avere lo stesso aspetto per diversi tipi di file. Si consideri, ad esempio, l'URI assoluto del pacchetto seguente.

pack://application:,,,/ResourceOrContentFile.xaml

Questo URI di pacchetto assoluto può fare riferimento a un file di risorse nell'assembly locale o a un file di contenuto. Lo stesso vale per l'URI relativo seguente.

/ResourceOrContentFile.xaml

Per determinare il tipo di file a cui fa riferimento un URI di pacchetto, WPF risolve gli URI per i file di risorse negli assembly locali e nei file di contenuto usando l'euristica seguente:

  1. Esaminare i metadata dell'assembly di un attributo AssemblyAssociatedContentFileAttribute corrispondente all'URI del pacchetto.

  2. Se viene trovato l'attributo AssemblyAssociatedContentFileAttribute, il percorso dell'URI pack fa riferimento a un file di contenuto.

  3. Se l'attributo AssemblyAssociatedContentFileAttribute non viene trovato, verificare i file di risorse del set che sono compilati nell'assembly locale.

  4. Se viene trovato un file di risorse che corrisponde al percorso dell'URI pack, il percorso dell'URI pack fa riferimento a un file di risorse.

  5. Se la risorsa non viene trovata, il Uri creato internamente non è valido.

La risoluzione URI non si applica agli URI che fanno riferimento ai seguenti elementi:

  • File di contenuto negli assembly a cui si fa riferimento: questi tipi di file non sono supportati da WPF.

  • File incorporati negli assembly a cui si fa riferimento: gli URI che li identificano sono univoci perché includono sia il nome dell'assembly a cui viene fatto riferimento che il suffisso ;component.

  • File del sito di origine: gli URI che li identificano sono univoci perché sono gli unici file che possono essere identificati dagli URI pack che contengono l'autorità di siteoforigin:///.

Una semplificazione che consente la risoluzione dell'URI di tipo pack è che il codice sia in qualche modo indipendente dalle posizioni dei file di risorse e di contenuto. Ad esempio, se si dispone di un file di risorse nell'assembly locale riconfigurato in modo che sia un file di contenuto, l'URI di tipo pack per la risorsa rimane invariato, così come il codice che usa l'URI pack.

Programmazione con Pack URIs

Molte classi WPF implementano proprietà che possono essere impostate con gli URI pack, tra cui:

Queste proprietà possono essere impostate sia dal markup che dal codice. In questa sezione vengono illustrate le costruzioni di base per entrambi e quindi vengono illustrati esempi di scenari comuni.

Uso degli URI di tipo Pack nel markup

Un URI di tipo pack viene specificato nel markup impostando l'elemento di un attributo con l'URI pack. Per esempio:

<element attribute="pack://application:,,,/File.xaml" />

La tabella 1 illustra i vari URI di pacchetto assoluti che è possibile specificare nel markup.

Tabella 1: URI assoluti del pacchetto nel markup

File URI pack assoluto
File di risorse - Assemblaggio locale "pack://application:,,,/ResourceFile.xaml"
File di risorse nella sottocartella - Assembly locale "pack://application:,,,/Subfolder/ResourceFile.xaml"
File di risorse - Assembly a cui si fa riferimento "pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml"
File di risorse nella sottocartella dell'assembly a cui si fa riferimento "pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
File di risorse nell'assembly di riferimento versionato "pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml"
File di contenuto "pack://application:,,,/ContentFile.xaml"
File di contenuto nella sottocartella "pack://application:,,,/Subfolder/ContentFile.xaml"
File del sito di origine "pack://siteoforigin:,,,/SOOFile.xaml"
File del sito di origine nella sottocartella "pack://siteoforigin:,,,/Subfolder/SOOFile.xaml"

La tabella 2 illustra i vari URI relativi del pacchetto che è possibile specificare nel markup.

Tabella 2: URI relativi del pacchetto nel linguaggio di marcatura

File URI pack relativo
File di risorse nell'assembly locale "/ResourceFile.xaml"
File di risorse nella sottocartella dell'assembly locale "/Subfolder/ResourceFile.xaml"
File di risorse nell'assembly a cui si fa riferimento "/ReferencedAssembly;component/ResourceFile.xaml"
File di risorse nella sottocartella dell'assembly a cui si fa riferimento "/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
File di contenuto "/ContentFile.xaml"
File di contenuto nella sottocartella "/Subfolder/ContentFile.xaml"

Uso degli URI di tipo Pack nel codice

Specifichi un URI pack nel codice istanziando la classe Uri e passando l'URI pack come parametro nel costruttore. Questo è illustrato nell'esempio seguente.

Uri uri = new Uri("pack://application:,,,/File.xaml");

Per impostazione predefinita, la classe Uri considera gli URI di tipo pack come assoluti. Di conseguenza, viene generata un'eccezione quando viene creata un'istanza della classe Uri con un URI pack relativo.

Uri uri = new Uri("/File.xaml");

Fortunatamente, l'overload Uri(String, UriKind) del costruttore della classe Uri accetta un parametro di tipo UriKind per consentire di specificare se un URI pack è assoluto o relativo.

// Absolute URI (default)
Uri absoluteUri = new Uri("pack://application:,,,/File.xaml", UriKind.Absolute);
// Relative URI
Uri relativeUri = new Uri("/File.xaml",
                        UriKind.Relative);

È consigliabile specificare solo Absolute o Relative quando si è certi che l'URI del pacchetto fornito sia uno o l'altro. Se non si conosce il tipo di URI pack usato, ad esempio quando un utente immette un URI pack in fase di esecuzione, usare invece RelativeOrAbsolute.

// Relative or Absolute URI provided by user via a text box
TextBox userProvidedUriTextBox = new TextBox();
Uri uri = new Uri(userProvidedUriTextBox.Text, UriKind.RelativeOrAbsolute);

La tabella 3 illustra i vari URI relativi del pacchetto che è possibile specificare nel codice usando System.Uri.

Tabella 3: URI assoluti del pacchetto nel codice

File URI pack assoluto
File di risorse - Assemblaggio locale Uri uri = new Uri("pack://application:,,,/ResourceFile.xaml", UriKind.Absolute);
File risorsa nella sottocartella - Assemblaggio locale Uri uri = new Uri("pack://application:,,,/Subfolder/ResourceFile.xaml", UriKind.Absolute);
File di risorse - Assembly a cui si fa riferimento Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Absolute);
File di risorse nella sottocartella dell'assembly a cui si fa riferimento Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Absolute);
File di risorse nell'assembly di riferimento versionato Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml", UriKind.Absolute);
File di contenuto Uri uri = new Uri("pack://application:,,,/ContentFile.xaml", UriKind.Absolute);
File di contenuti nella sottocartella Uri uri = new Uri("pack://application:,,,/Subfolder/ContentFile.xaml", UriKind.Absolute);
File del sito di origine Uri uri = new Uri("pack://siteoforigin:,,,/SOOFile.xaml", UriKind.Absolute);
File del sito di origine nella sottocartella Uri uri = new Uri("pack://siteoforigin:,,,/Subfolder/SOOFile.xaml", UriKind.Absolute);

La tabella 4 illustra i vari URI relativi del pacchetto che è possibile specificare nel codice usando System.Uri.

Tabella 4: URI relativi del pacchetto nel codice

File URI relativo del pacchetto
File di risorse - Assemblaggio locale Uri uri = new Uri("/ResourceFile.xaml", UriKind.Relative);
File di risorse nella sottocartella - Assembly locale Uri uri = new Uri("/Subfolder/ResourceFile.xaml", UriKind.Relative);
File di risorse - Assembly a cui si fa riferimento Uri uri = new Uri("/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Relative);
File di risorse nella sottocartella - Assembly a cui si fa riferimento Uri uri = new Uri("/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Relative);
File di contenuto Uri uri = new Uri("/ContentFile.xaml", UriKind.Relative);
File di contenuto nella sottocartella Uri uri = new Uri("/Subfolder/ContentFile.xaml", UriKind.Relative);

Scenari comuni di URI pacchetto

Le sezioni precedenti hanno illustrato come costruire URI di pacchetto per identificare i file di risorsa, contenuto e sito di origine. In WPF queste costruzioni vengono usate in diversi modi e le sezioni seguenti illustrano diversi utilizzi comuni.

Specificare l'interfaccia utente da visualizzare all'avvio di un'applicazione

StartupUri specifica la prima interfaccia utente da visualizzare all'avvio di un'applicazione WPF. Per le applicazioni autonome, l'interfaccia utente può essere una finestra, come illustrato nell'esempio seguente.

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

Le applicazioni autonome e le applicazioni browser XAML (XBAP) possono anche specificare una pagina come interfaccia utente iniziale, come illustrato nell'esempio seguente.

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

Se l'applicazione è un'applicazione autonoma e viene specificata una pagina con StartupUri, WPF apre un NavigationWindow per ospitare la pagina. Per gli XBAP, la pagina viene visualizzata nel browser host.

Navigare su una pagina

Nell'esempio seguente viene illustrato come passare a una pagina.

<Page
  xmlns="http://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>

Per altre informazioni sui vari modi per spostarsi in WPF, vedere Cenni preliminari sulla navigazione.

Specificare un'icona della finestra

Nell'esempio seguente viene illustrato come usare un URI per specificare l'icona di una finestra.

<Window
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  x:Class="SDKSample.MainWindow"
    Icon="WPFIcon1.ico">
</Window>

Per altre informazioni, vedere Icon.

Caricamento di file immagine, audio e video

WPF consente alle applicazioni di usare un'ampia gamma di tipi di supporti, che possono essere identificati e caricati con URI di tipo pack, come illustrato negli esempi seguenti.

<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" />

Per altre informazioni sull'uso del contenuto multimediale, vedere Graphics and Multimedia.

Caricamento di un dizionario risorse dal sito di origine

I dizionari risorse (ResourceDictionary) possono essere usati per supportare i temi dell'applicazione. Un modo per creare e gestire i temi consiste nel creare più temi come dizionari risorse che si trovano nel sito di origine di un'applicazione. Ciò consente di aggiungere e aggiornare i temi senza ricompilare e ridistribuire un'applicazione. Questi dizionari delle risorse possono essere identificati e caricati utilizzando i pack URI, come mostrato nell'esempio seguente.

<Application
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    StartupUri="HomePage.xaml">
  <Application.Resources>
    <ResourceDictionary Source="pack://siteoforigin:,,,/PageTheme.xaml" />
  </Application.Resources>
</Application>

Per una panoramica dei temi in WPF, vedere Styling e Templating.

Vedere anche