Pack URI en WPF

En Windows Presentation Foundation (WPF), los identificadores uniformes de recursos (URI) se usan para identificar y cargar archivos de muchas maneras, incluidos los siguientes:

• Especificar la interfaz de usuario (UI) para mostrar cuándo se inicia una aplicación por primera vez.

• Carga de imágenes.

• Navegar a páginas.

• Carga de archivos de datos no ejecutables.

Además, los URI se pueden usar para identificar y cargar archivos desde una variedad de ubicaciones, incluidos los siguientes:

• La asamblea actual

• Ensamblado al que se hace referencia.

• Ubicación relativa de un ensamblaje.

• Sitio de origen de la aplicación.

Para proporcionar un mecanismo coherente para identificar y cargar estos tipos de archivos desde estas ubicaciones, WPF aprovecha la extensibilidad del esquema URI del paquete. En este tema se proporciona información general sobre el esquema, se explica cómo construir URI de paquete para una variedad de escenarios, se describen los URI absolutos y relativos y la resolución de URI, antes de mostrar cómo usar los URI de paquete tanto del marcado como del código.

Esquema de URI del paquete

La especificación Open Packaging Conventions (OPC) usa el esquema de URI del paquete, que describe un modelo para organizar e identificar contenido. Los elementos clave de este modelo son paquetes y partes, donde un paquete es un contenedor lógico para una o varias partes lógicas. En la ilustración siguiente se muestra este concepto.

Para identificar partes, la especificación de OPC aprovecha la extensibilidad de RFC 2396 (Identificadores uniformes de recursos (URI): sintaxis genérica) para definir el esquema de URI del paquete.

El esquema especificado por un URI se define mediante su prefijo; http, ftp y file son ejemplos conocidos. El esquema de URI del paquete usa "pack" como esquema y contiene dos componentes: autoridad y ruta de acceso. A continuación se muestra el formato de un URI de paquete.

ruta de acceso de autenticación/ de pack://

La autoridad especifica el tipo de paquete que contiene una parte, mientras que la ruta especifica la ubicación de una parte dentro de un paquete.

Este concepto se ilustra mediante la ilustración siguiente:

Los paquetes y partes son análogos a las aplicaciones y los archivos, donde una aplicación (paquete) puede incluir uno o varios archivos (partes), entre los que se incluyen:

• Archivos de recursos que se compilan en el ensamblado local.

• Archivos de recursos que se compilan en un ensamblado al que se hace referencia.

• Archivos de recursos que se compilan en un ensamblado de referencia.

• Archivos de contenido.

• Sitio de archivos de origen.

Para acceder a estos tipos de archivos, WPF admite dos autoridades: application:/// y siteoforigin:///. La autoridad de application:/// identifica los archivos de datos de la aplicación que se conocen en tiempo de compilación, incluidos los archivos de recursos y contenido. La autoridad de siteoforigin:/// identifica el sitio de archivos de origen. El ámbito de cada autoridad se muestra en la ilustración siguiente.

Nota:

El componente de autoridad de un URI de paquete es un URI incrustado que apunta a un paquete y debe ajustarse a RFC 2396. Además, el carácter "/" debe reemplazarse por el carácter ",", y los caracteres reservados como "%" y "?" deben ser escapados. Consulte OPC para obtener más información.

En las secciones siguientes se explica cómo construir URI de paquete mediante estas dos autoridades junto con las rutas de acceso adecuadas para identificar los archivos de recursos, contenido y sitio de origen.

URI del paquete de archivos de recursos

Los archivos de recursos se configuran como elementos de MSBuild Resource y se compilan en ensamblados. WPF admite la construcción de URI de paquete que se pueden usar para identificar los archivos de recursos que se compilan en el ensamblado local o se compilan en un ensamblado al que se hace referencia desde el ensamblado local.

Archivo de recursos de ensamblado local

El URI del paquete de un archivo de recursos que se compila en el ensamblado local utiliza la siguiente autoridad y ruta de acceso.

• Autoridad: application:///.

• Ruta de acceso: el nombre del archivo de recursos, incluida su ruta de acceso, en relación con la raíz de la carpeta del proyecto del ensamblado local.

En el ejemplo siguiente se muestra el URI del paquete para un archivo de recursos XAML que se encuentra en la raíz de la carpeta del proyecto del ensamblado local.

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

En el ejemplo siguiente se muestra el URI del paquete para un archivo de recursos XAML que se encuentra en una subcarpeta de la carpeta del proyecto del ensamblado local.

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

Archivo de recursos de ensamblado al que se hace referencia

El URI del paquete de un archivo de recurso que se compila en un ensamblado al que se hace referencia utiliza la siguiente autoridad y ruta de acceso:

• Autoridad: application:///.

• Ruta: El nombre de un archivo de recursos que está compilado en un ensamblado al que se hace referencia. La ruta de acceso debe cumplir el formato siguiente:

  AssemblyShortName{;Versión]{;PublicKey];component/Path

  • AssemblyShortName: nombre corto del ensamblado al que se hace referencia.

  • ; Versión [opcional]: la versión del ensamblado al que se hace referencia que contiene el archivo de recursos. Esto se usa cuando se cargan dos o más ensamblados a los que se hace referencia con el mismo nombre corto.

  • ; PublicKey [opcional]: la clave pública que se usó para firmar el ensamblado al que se hace referencia. Esto se usa cuando se cargan dos o más ensamblados a los que se hace referencia con el mismo nombre corto.

  • ;component: especifica que el ensamblado al que se hace referencia proviene del ensamblado local.

  • /Path: el nombre del archivo de recursos, incluida su ruta de acceso, en relación con la raíz de la carpeta del proyecto del ensamblado al que se hace referencia.

En el ejemplo siguiente se muestra el URI del paquete para un archivo de recursos XAML que se encuentra en la raíz de la carpeta del proyecto del ensamblado al que se hace referencia.

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

En el ejemplo siguiente se muestra el URI del paquete de un archivo de recursos XAML que se encuentra en una subcarpeta de la carpeta del proyecto del ensamblado al que se hace referencia.

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

En el ejemplo siguiente se muestra el URI del paquete de un archivo de recursos XAML que se encuentra en la carpeta raíz de una carpeta de proyecto del ensamblado específica de la versión a la que se hace referencia.

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

Tenga en cuenta que la sintaxis del URI del paquete para los archivos de recursos de ensamblaje referenciados solo se puede utilizar con la autoridad application:///. Por ejemplo, no se admite lo siguiente en WPF.

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

URI del paquete de archivos de contenido

El URI del paquete de un archivo de contenido usa la siguiente autoridad y ruta de acceso:

• Autoridad: application:///.

• Ruta de acceso: el nombre del archivo de contenido, incluida su ruta de acceso en relación con la ubicación del sistema de archivos del ensamblado ejecutable principal de la aplicación.

En el ejemplo siguiente se muestra el URI del paquete para un archivo de contenido XAML, ubicado en la misma carpeta que el ensamblado ejecutable.

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

En el ejemplo siguiente se muestra el URI del paquete para un archivo de contenido XAML, ubicado en una subcarpeta relativa al ensamblado ejecutable de la aplicación.

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

Nota:

No se puede navegar a los archivos de contenido HTML. El esquema de URI solo admite la navegación a archivos HTML que se encuentran en el sitio de origen.

URIs del Sitio de Origen del Paquete

El URI del paquete para un archivo de origen de sitio usa la siguiente autoridad y ruta de acceso:

• Autoridad: siteoforigin:///.

• Ruta de acceso: el nombre del archivo de origen del sitio, incluida su ruta de acceso relativa a la ubicación desde la que se inició el ensamblado ejecutable.

En el ejemplo siguiente se muestra el pack URI para un archivo de origen de un sitio XAML, almacenado en la ubicación desde la cual se lanza el ensamblado ejecutable.

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

En el ejemplo siguiente se muestra el URI del paquete de un archivo de origen del sitio XAML, almacenado en subcarpeta que es relativa a la ubicación desde la que se inicia el ensamblado ejecutable de la aplicación.

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

Archivos de página

Los archivos XAML configurados como elementos de MSBuild Page se compilan en ensamblados de la misma manera que los archivos de recursos. Por lo tanto, los elementos de MSBuild Page se pueden identificar mediante URI de paquete para archivos de recursos.

Los tipos de archivos XAML que se suelen configurar como elementos de MSBuildPage tienen uno de los siguientes elementos como su elemento raíz:

• System.Windows.Window

• System.Windows.Controls.Page

• System.Windows.Navigation.PageFunction<T>

• System.Windows.ResourceDictionary

• System.Windows.Documents.FlowDocument

• System.Windows.Controls.UserControl

URI absolutos frente al paquete relativo

Un URI de paquete completo incluye el esquema, la autoridad y la ruta de acceso, y se considera un URI de paquete absoluto. Como simplificación para los desarrolladores, los elementos XAML normalmente permiten establecer atributos adecuados con un URI de paquete relativo, que incluye solo el camino.

Por ejemplo, considere el siguiente URI de paquete absoluto para un archivo de recursos en el ensamblado local.

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

El URI del paquete relativo que hace referencia a este archivo de recursos sería el siguiente.

/ResourceFile.xaml

Nota:

Dado que los archivos del sitio de origen no están asociados a ensamblados, solo se pueden referenciar mediante URIs de paquete absolutos.

De forma predeterminada, un URI de paquete relativo se considera relativo a la ubicación del marcado o código que contiene la referencia. Sin embargo, si se usa una barra diagonal inversa inicial, la referencia del URI del paquete relativo se considera relativa a la raíz de la aplicación. Por ejemplo, considere la siguiente estructura del proyecto.

App.xaml

Page2.xaml

\SubFolder

+ Page1.xaml

+ Page2.xaml

Si Page1.xaml contiene un URI que hace referencia a Root\SubFolder\Page2.xaml, la referencia puede usar el siguiente URI del paquete relativo.

Page2.xaml

Si Page1.xaml contiene un URI que hace referencia a Root\Page2.xaml, la referencia puede usar el siguiente URI de paquete relativo.

/Page2.xaml

Resolución de URI de paquete

El formato de los URI de paquete permite que los URI de paquete para distintos tipos de archivos parezcan iguales. Por ejemplo, considere el siguiente URI de paquete absoluto.

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

Este URI de paquete absoluto podría hacer referencia a un archivo de recursos en el ensamblado local o en un archivo de contenido. Lo mismo ocurre con el siguiente URI relativo.

/ResourceOrContentFile.xaml

Para determinar el tipo de archivo al que hace referencia un URI de paquete, WPF resuelve los URI de los archivos de recursos en ensamblados locales y archivos de contenido mediante la heurística siguiente:

1. Sondee los metadatos del ensamblado para un AssemblyAssociatedContentFileAttribute atributo que coincida con el URI del paquete.

2. Si se encuentra el AssemblyAssociatedContentFileAttribute atributo, la ruta de acceso del URI del paquete hace referencia a un archivo de contenido.

3. Si no se encuentra el AssemblyAssociatedContentFileAttribute atributo , sondee los archivos de recursos establecidos que se compilan en el ensamblado local.

4. Si se encuentra un archivo de recursos que coincide con la ruta de acceso del URI del paquete, la ruta de acceso del URI del paquete hace referencia a un archivo de recursos.

5. Si no se encuentra el recurso, el elemento creado Uri internamente no es válido.

La resolución de URI no se aplica a los URI que hacen referencia a lo siguiente:

• Archivos de contenido en ensamblados a los que se hace referencia: WPF no admite estos tipos de archivo.

• Archivos incrustados en ensamblados a los que se hace referencia: los URI que los identifican son únicos porque incluyen el nombre del ensamblado al que se hace referencia y el ;component sufijo.

• Sitio de archivos de origen: los URIs que los identifican son únicos porque son los únicos archivos que pueden ser identificados por los URIs del paquete que contienen la autoridad siteoforigin:///.

Una simplificación que permite la resolución de URI del paquete es que el código sea algo independiente de las ubicaciones de los archivos de recursos y de contenido. Por ejemplo, si tiene un archivo de recursos en el ensamblado local que se vuelve a configurar para que sea un archivo de contenido, el URI del paquete para el recurso sigue siendo el mismo, igual que el código que usa el URI del paquete.

Programación con URI de paquete

Muchas clases de WPF implementan propiedades que se pueden establecer con URI de paquete, entre las que se incluyen:

• Application.StartupUri

• Frame.Source

• NavigationWindow.Source

• Hyperlink.NavigateUri

• Window.Icon

• Image.Source

Estas propiedades se pueden establecer desde el marcado y el código fuente. Esta sección demuestra las construcciones básicas para ambos y luego muestra ejemplos de escenarios comunes.

Uso de Pack URI en lenguaje de marcado

Un URI de paquete se especifica en el marcado mediante la asignación del URI del paquete a un atributo del elemento. Por ejemplo:

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

En la tabla 1 se muestran los distintos URI de paquete absolutos que puede especificar en el marcado.

Tabla 1: URI de paquete absoluto en marcado

Archivo	URI de paquete absoluto
Archivo de recursos: ensamblado local	"pack://application:,,,/ResourceFile.xaml"
Archivo de recursos en subcarpeta: ensamblado local	"pack://application:,,,/Subfolder/ResourceFile.xaml"
Archivo de recursos: ensamblado al que se hace referencia	"pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml"
Archivo de recursos en la subcarpeta del ensamblado al que se hace referencia	"pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
Archivo de recursos en el ensamblado al que se hace referencia con versiones	"pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml"
Archivo de contenido	"pack://application:,,,/ContentFile.xaml"
Archivo de contenido en la subcarpeta	"pack://application:,,,/Subfolder/ContentFile.xaml"
Sitio de archivo de origen	"pack://siteoforigin:,,,/SOOFile.xaml"
Sitio de archivo de origen en la subcarpeta	"pack://siteoforigin:,,,/Subfolder/SOOFile.xaml"

En la tabla 2 se muestran los distintos URI de paquete relativo que se pueden especificar en el marcado.

Tabla 2: URI de paquete relativo en marcado

Archivo	URI del paquete relativo
Archivo de recursos en el ensamblado local	"/ResourceFile.xaml"
Archivo de recursos en la subcarpeta del ensamblado local	"/Subfolder/ResourceFile.xaml"
Archivo de recursos en ensamblado al que se hace referencia	"/ReferencedAssembly;component/ResourceFile.xaml"
Archivo de recursos en la subcarpeta del ensamblado al que se hace referencia	"/ReferencedAssembly;component/Subfolder/ResourceFile.xaml"
Archivo de contenido	"/ContentFile.xaml"
Archivo de contenido en la subcarpeta	"/Subfolder/ContentFile.xaml"

Uso de Pack URI en código

Para especificar un URI de paquete en el código, cree una instancia de la Uri clase y pase el URI del paquete como parámetro al constructor. Esto se muestra en el ejemplo siguiente.

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

De forma predeterminada, la clase considera que los Uri URI de paquete son absolutos. Por lo tanto, se genera una excepción cuando se crea una instancia de la Uri clase con un URI de paquete relativo.

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

Afortunadamente, la Uri(String, UriKind) sobrecarga del constructor de la clase Uri acepta un parámetro de tipo UriKind para especificar si un URI del paquete es absoluto 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);

Debe especificar solo Absolute o Relative cuando esté seguro de que el URI del paquete proporcionado es uno o otro. Si no conoce el tipo de URI de paquete que se usa, como cuando un usuario escribe un URI de paquete en tiempo de ejecución, use RelativeOrAbsolute en su lugar.

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

En la tabla 3 se muestran los distintos URI de paquete relativos que puede especificar en el código mediante System.Uri.

Tabla 3: URI de paquete absoluto en código

Archivo	URI de paquete absoluto
Archivo de recursos: ensamblado local	Uri uri = new Uri("pack://application:,,,/ResourceFile.xaml", UriKind.Absolute);
Archivo de recursos en subcarpeta: ensamblado local	Uri uri = new Uri("pack://application:,,,/Subfolder/ResourceFile.xaml", UriKind.Absolute);
Archivo de recursos: ensamblado al que se hace referencia	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Absolute);
Archivo de recursos en la subcarpeta del ensamblado al que se hace referencia	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Absolute);
Archivo de recursos en el ensamblado al que se hace referencia con versiones	Uri uri = new Uri("pack://application:,,,/ReferencedAssembly;v1.0.0.0;component/ResourceFile.xaml", UriKind.Absolute);
Archivo de contenido	Uri uri = new Uri("pack://application:,,,/ContentFile.xaml", UriKind.Absolute);
Archivo de contenido en la subcarpeta	Uri uri = new Uri("pack://application:,,,/Subfolder/ContentFile.xaml", UriKind.Absolute);
Sitio de archivo de origen	Uri uri = new Uri("pack://siteoforigin:,,,/SOOFile.xaml", UriKind.Absolute);
Sitio de archivo de origen en la subcarpeta	Uri uri = new Uri("pack://siteoforigin:,,,/Subfolder/SOOFile.xaml", UriKind.Absolute);

En la tabla 4 se muestran los distintos URI de paquete relativos que puede especificar en el código mediante System.Uri.

Tabla 4: URIs de paquetes relativos en código

Archivo	URI del paquete relativo
Archivo de recursos: ensamblado local	Uri uri = new Uri("/ResourceFile.xaml", UriKind.Relative);
Archivo de recursos en subcarpeta: ensamblado local	Uri uri = new Uri("/Subfolder/ResourceFile.xaml", UriKind.Relative);
Archivo de recursos: ensamblado al que se hace referencia	Uri uri = new Uri("/ReferencedAssembly;component/ResourceFile.xaml", UriKind.Relative);
Archivo de recursos en subcarpeta: ensamblado al que se hace referencia	Uri uri = new Uri("/ReferencedAssembly;component/Subfolder/ResourceFile.xaml", UriKind.Relative);
Archivo de contenido	Uri uri = new Uri("/ContentFile.xaml", UriKind.Relative);
Archivo de contenido en la subcarpeta	Uri uri = new Uri("/Subfolder/ContentFile.xaml", UriKind.Relative);

Escenarios comunes de URI de paquete

En las secciones anteriores se ha descrito cómo construir URI de paquete para identificar los archivos de recursos, contenido y sitio de origen. En WPF, estas construcciones se usan de varias maneras, y en las secciones siguientes se tratan varios usos comunes.

Especificar la interfaz de usuario que se va a mostrar cuando se inicia una aplicación

StartupUri especifica la primera interfaz de usuario que se mostrará cuando se inicia una aplicación WPF. En el caso de las aplicaciones independientes, la interfaz de usuario puede ser una ventana, como se muestra en el ejemplo siguiente.

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

Las aplicaciones independientes y las aplicaciones de explorador XAML (XBAPs) también pueden especificar una página como la interfaz de usuario inicial, como se muestra en el ejemplo siguiente.

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

Si la aplicación es una aplicación independiente y se especifica una página con StartupUri, WPF abre un NavigationWindow para hospedar la página. Para XBAP, la página se muestra en el explorador host.

Navegar a una página

En el ejemplo siguiente se muestra cómo navegar a una página.

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

Para obtener más información sobre las distintas formas de navegar en WPF, vea Información general de navegación.

Especificar un icono de ventana

En el ejemplo siguiente se muestra cómo usar un URI para especificar el icono de una ventana.

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

Para obtener más información, consulte Icon.

Carga de archivos de imagen, audio y vídeo

WPF permite a las aplicaciones usar una amplia variedad de tipos de medios, todos los cuales se pueden identificar y cargar con URI de paquete, como se muestra en los ejemplos siguientes.

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

Para obtener más información sobre cómo trabajar con contenido multimedia, consulta Gráficos y multimedia.

Carga de un diccionario de recursos desde el sitio de origen

Los diccionarios de recursos (ResourceDictionary) se pueden usar para soportar los temas de la aplicación. Una manera de crear y administrar temas es crear varios temas como diccionarios de recursos que se encuentran en el sitio de origen de una aplicación. Esto permite agregar y actualizar temas sin volver a compilar y volver a implementar una aplicación. Estos diccionarios de recursos se pueden identificar y cargar mediante URI de paquete, que se muestra en el ejemplo siguiente.

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

Para obtener información general sobre los temas en WPF, vea Aplicar estilos y plantillas.

Consulte también

• Recursos, contenido y archivos de datos de la aplicación WPF