Resource Files
Microsoft Silverlight will reach end of support after October 2021. Learn more.
Resource files are typically any non-executable data file used by your application, such as image, audio, and video files. A resource file can also have specific meanings in certain contexts. For example, in the context of application localization, resource files refer to .resx files, which you can deploy in localized satellite assemblies.
With Silverlight, you can deploy resource files in the following ways:
As individual files in the application package.
As individual files that you retrieve on demand.
As files embedded in an assembly in the application package.
As files embedded in an assembly in an external library package.
As files embedded in an assembly that you retrieve on demand.
You typically refer to a resource file in code or XAML by using a Uniform Resource Identifier (URI). The required URI format depends on how the file is deployed. You also have the option of specifying a relative or absolute URI.
This topic describes how to configure the deployment location of your resource files and refer to them by URI. For information about application packaging and how to structure your application for optimal responsiveness, see Application Structure. For information about deployment and localization, see Deployment and Localization.
Configuring Your Resource Files
In Visual Studio, you can add resource files to your Silverlight project and then configure them for deployment by setting their Build Action values. You can use the following build actions for resource files in Silverlight projects:
Resource. This build action will embed the file in the project assembly. You can use this option with application and library projects, and deploy the assemblies inside or outside the application package.
Content. This build action will include the file in the application package without embedding it in the project assembly. Use this option for resource files shared by multiple assemblies in the package.
None. This build action will not include the file in the application package or assembly. Use this option for resource files that you want to retrieve on demand. You will typically deploy on-demand files at the same server location as your application package.
.gif "Caution note") Caution: |
|---|
The Properties window in Visual Studio provides several other values in the Build Action drop-down list. However, you can use only the previous three values with Silverlight projects. In particular, Silverlight embedded resources must always use the Resource build action, and not the Embedded Resource build action, which uses a format that Silverlight cannot recognize. |
You can change the build action if you decide to share an embedded resource file or retrieve it on demand. In this case, you must rebuild and redeploy your application. If you do not use relative URIs, you must also update your URI references before you rebuild. The following sections describe the URI format options.
.gif "Note") Note: |
|---|
When you reference a font file by URI, you must embed the font file within an assembly and use the URI syntax for embedded files. For more information, see the FontFamily class overview. As an alternative, you can set the FontSource property that exists on various controls. For more information, see Text and Fonts. |
Using resource files that were compiled with the .NET Framework version 1.1 will cause a NotSupportedException if they contain a Boolean, Char, Byte, or Stream type.
Absolute and Relative URIs
Silverlight supports absolute and relative URIs, and provides a fallback mechanism for locating files by using relative URIs.
Absolute URIs specify the exact location of a resource file, and bypass the fallback mechanism. For example, "https://www.contoso.com/resources/OnDemand.png" represents a file in the resources folder on specified domain. Absolute URIs are required for resource files located on a domain other than the host domain of the application package.
Relative URIs specify the location of a resource file relative to the application root or the referencing XAML.
URIs Relative to the Application Root
A relative URI with a leading slash represents a location relative to the application root. For example: "/resources/image.png".
The application root is the root folder of the application package or the location of the application package on the server. The relative-URI fallback mechanism searches the application package first, and then the server. If you include a path after the leading slash, the same folder hierarchy is searched in both locations.
URIs Relative to the Referencing XAML
A relative URI without a leading slash represents a location relative to the referencing XAML. If you use a relative URI in code, then the referencing XAML is the XAML that your code manipulates.
If the referencing XAML is located in a folder, you can refer to files in other folders relative to that location. However, you cannot search above the application root. For example: "../resources/image.png". This URI searches in a resources folder at the same level as the folder that contains your XAML, assuming that folder is not the application root.
If the referencing XAML is loaded from the application package, but the referenced resource file is not found, then the default fallback mechanism is used. The path of the referencing XAML in the application package is used to look on the server. For example, consider a XAML file in the following location within the application package: /pages/xaml/MyPage.xaml. In this case, the fallback mechanism will look for "../resources/image.png" on the server at the following location: /pages/resources/image.png.
If the referencing XAML is compiled into an assembly, then the resource file must be embedded in the same assembly. In this case, the URI fallback mechanism is the one provided by the ResourceManager class. This fallback mechanism uses language and culture settings to look for a resource file in a satellite assembly. For more information, see Localizing Silverlight-based Applications.
URIs to Other Assemblies
You can also reference resource files embedded in an assembly other than the one that contains the referencing XAML. In this case, the URI uses the following format: "/assemblyShortName;component/resourceLocation". For example: "/SilverlightLibraryAssembly;component/image.png". Note that the leading slash and the component keyword (followed by a slash) are required.
As with other embedded resources, this URI format uses the fallback mechanism provided by the ResourceManager class.