Working With Resources

PDF for offline use
Related Articles:
Related Recipes:

Let us know how you feel about this

Translation Quality


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.

Resources Folder


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:

  1. If it has not already been created by the project template, add a Resources directory in the Xamarin.iOS project.
  2. Add the required files to the Resources directory.
  3. 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.
  4. 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 Default images are present). Additional images should be added if iPad support is required.

Refer to the Working with Images and Working with Property Lists documents for more information on icon and launch images.

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 en.lproj and 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 Resources and 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:

<BundleResource Include="Resources/Bar-release.png"><LogicalName>Bar.png</LogicalName></BundleResource>

In this example the application bundle will contain the image named Bar.png in the bundle root (renamed from the original Bar-release.png).

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 ItemGroup element, as shown here, to select which files to include in the bundle:

<ItemGroup Condition="'$(Configuration)'!='Debug'">
  <BundleResource Include="Resources/values/strings.xml" />
<ItemGroup  Condition="'$(Configuration)'=='Debug'">
  <BundleResource Include="Resources-Debug/values/strings.xml"/>

In this case the Debug build will have a different strings.xml than other build configurations (notice the == and != operators in the Condition attribute).

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.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.