Working With Resources
- PDF for offline use
- Related Articles:
- Related Recipes:
Let us know how you feel about this
last updated: 2017-03
This document introduces the Resources directory and the BundleResource build action.
iOS requires that app resource files including icons and launch images be placed in the application's root directory. This makes it hard to keep track of image files and results in a messy project structure. With Xamarin, there is no need to clutter the root project directory of your iOS application with icons or other bundled resources. Instead, the BundledResource build action lets you put these files in a separate Resources directory, whose content are placed in the root of the application during the build process. This guide demonstrates how to use the Resources directory to organize icons, launch images, and other files. It covers both typical and advanced use cases for resources.
NOTE: The information in this section is provided for historical reference only. Starting with iOS 9, App Icons should be provided using Image Assets and Launch Screens should be created with Storyboards.
iOS applications require icons and launch images. To help keep these organized, Visual Studio for Mac supports a special build action called BundleResource and a Resources folder where these files can be stored.
In addition to the required images, you can use BundleResource to manage any other files required by your application, such as localized string files, sound files or anything else that must be embedded in your app.
Steps to use this feature are:
- If it has not already been created by the project template, add a Resources directory in the Xamarin.iOS project.
- Add the required files to the Resources directory.
- Visual Studio for Mac should automatically choose the BundleResource build action, but you can set the Build Action manually by right-clicking on the file.
- The build process automatically places the resource files in the bundle root . The directory structure within the Resources directory will be preserved, but it will be based in the app bundle’s root.
The following screenshot illustrates a Resources folder in a Xamarin.iOS project. We are using the context-menu to apply the BundleResource build action to a file:
The Resources directory typically contains the following
files for an iPhone application (only iPhone-sized
are present). Additional images should be added if iPad support is required.
Other Types of Resource Files
The Resources folder can also include other file types, including localized string files, sounds and other data files that the application requires. For example, the screenshot below illustrates two localized languages and a sound file added to the Resources directory along with app images:
The directory structure is preserved during the build process, so the
application bundle will contain the
fr.lproj directories in its root. This is important because iOS
requires these resources to be in the root. If your application supports many languages,
being able to group the resources in the Resources directory rather than the
project root can greatly simplify your solution structure by separating the
localization files from the code.
Resources in Binding Projects
The Resources directory can also be used in Xamarin.iOS Binding Projects. Files marked as BundleResource in a Binding Project will be embedded into the binding assembly and extracted to the correct location when referenced by a Xamarin.iOS application project.
The native library in the Binding Project will then be able to access the files in the expected location.
Advanced Resource Management
Most users will find the Resources directory useful without any further
customization. However, in special cases, additional features of the BundleResource item type can be accessed by editing
csproj file directly. This section provides an overview of several customization options.
Adding Additional Resource Folders
The Resources directory is defined by the
IPhoneResourcePrefix element in the
csproj file. For
larger projects or to manage resources in multiple directories, additional
directories can be configured by editing the
csproj file directly
to include additional directory names, as illustrated by the following code sample:
In this example, files and subdirectories placed in both the
Localizations directories will be copied
to the root of the application bundle.
Overriding Resource Paths
For more granular control, the
LogicalName item metadata can be
used to specify the resource path explicitly for a given
BundleResource file, as illustrated by the code sample below:
In this example the application bundle will contain the image named
Bar.png in the bundle root (renamed from the original
Conditionally Including Resources
In certain situations our app may require different resources used in different configurations but with the same effective path. This can be achieved by having multiple resource directories containing files with the same relative paths within these different directories, and using MSBuild to conditionally include different files in different configurations.
The condition can be specified on the
BundleResource element, so
that the image
Bar.png in the bundle root is different in the Debug or Release builds:
<BundleResource Include="Resources/Bar-release.png" Condition="'$(Configuration)'='Release'"><LogicalName>Bar.png</LogicalName></BundleResource> <BundleResource Include="Resources/Bar.png" Condition="'$(Configuration)'!='Release'"><LogicalName>Bar.png</LogicalName></BundleResource>
Alternatively the condition can be specified on an
element, as shown here, to select which files to include in the bundle:
<PropertyGroup> <IPhoneResourcePrefix>Resources;Resources-Debug</IPhoneResourcePrefix> </PropertyGroup> <ItemGroup Condition="'$(Configuration)'!='Debug'"> <BundleResource Include="Resources/values/strings.xml" /> </ItemGroup> <ItemGroup Condition="'$(Configuration)'=='Debug'"> <BundleResource Include="Resources-Debug/values/strings.xml"/> </ItemGroup>
In this case the
Debug build will have a different
strings.xml than other build configurations (notice the == and !=
operators in the
This section introduced working with the Resources directory for simple and advanced use cases.
This guide introduced the Resources folder and the BundleResource build action, and illustrated how both of these features make it easy to manage files required by an application.