Posted on:
Categories: SharePoint
Description:

​I like using resource files. Not only are they essential for multi-lingual web development, it is good code practice to separate UI from business logic and centralize definitions of UI strings. I will not be going into details what resource files are but an excellent introduction can be found here. Instead I will focus on how we use them in SharePoint.

There are a few different ways to use resources in SharePoint depending on where they are being used. SharePoint resources are generally separated into 3 categories: Embedded, Provisioning and Application (Runtime).

Embedded resources

As the title suggests, they are resource files that are embedded in an assembly. They can be used in any vanilla ASP.Net sites. To add an embedded resource in Visual Studio, you right click a SharePoint project and add New Item. Under General category, select Resources File.

Add New Resource Item

After the file is added, if you select the file, Build Action in the Properties window should say Embedded Resource.

Build Action for Embedded Resource

Apart from Provisioning resources which I will be describing next, all resource files are added as Embedded Resource by default.

To reference a resource string, use the following in your code behinds or classes: 

Resource.MsgEmbeddedResource

where Resource is the name of the resource file without the file extension and MsgEmbeddedResource is the resource key I created for this example.

Embedded Resource File

Embedded resources are great for development as Visual Studio provides intellisense for path to resource strings.

Provisioning resources

They include those that are used during provisioning of elements like features, list templates etc. To add a provisioning resource in Visual Studio, you first need to add a SharePoint Mapped Folder to {SharePointRoot}\Resources.

Add SharePoint Mapped Folder

Select the newly added mapped folder and add New Item. Under General category, select Resources File. I usually name my resource file same as my project name. This time you will notice the Build Action is set to Content. As far as I know there is nothing preventing you from changing the Build Action to Embedded Resource to make it both an embedded and provisioning resource.

Build Action for Provisioning Resource

To reference a resource string, use the following in your code behinds or classes:

SPUtility.GetLocalizedString("$Resources:MsgSharePointGlobalResource", 
"Softlanding.SharePoint", SPContext.Current.Web.Language);

where Softlanding.SharePoint is the name of the resource file without the file extension and MsgSharePointGlobalResource is the resource key I created.

Provisioning Resource Content

As mentioned earlier, provisioning resources can be used in provisioning elements. For example you can use them in feature titles and description.  Select a feature and in Properties specify the Default Resource File, in this case Softlanding.SharePoint.

Default Resource File

In feature title and description, you can then enter:

Title: $Resources:FeatureTitleAssets
Description: $Resources:FeatureDescriptionAssets

where FeatureTitleAssets and FeatureDescriptionAssets are resource keys I created for this example.

Resoyrce Strings in Feature Title and Description

If you don’t specify the Default Resource File, you need to include it like the following:

Title: $Resources:Softlanding.SharePoint,FeatureTitleAssets
Description:$Resources:Softlanding.SharePoint,FeatureDescriptionAssets

Visual Studio also has an Add Feature Resource option that adds a resource file to a feature. Resource strings will be read from it if Default Resource File is not specified.

Add Feature Resource

Application (Runtime) resources

Application (Runtime) resources include those that are used by application pages (aspx) and user controls (ascx). They are stored in the root App_GlobalResources folder C:\inetpub\wwwroot\wss\VirtualDirectories\{port}\App_GlobalResources. Like embedded resources they can be used in any vanilla ASP.NET web sites.

Here comes the SharePoint twist. When a SharePoint web application is created, all resource files in the {SharePoint Root}\Config\Resources folder are copied to the root App_GlobalResources folder. If you would like a custom resource always available to new web applications, you would deploy it to the {SharePoint Root}\Config\Resources folder. However this custom resource file will not get copied over automatically to the root App_GlobalResources folder of existing web applications.

In majority of cases, deploying resource files to the root App_GlobalResources folder is sufficient. To do that, add an Empty Element to your SharePoint project. Delete elements.xml. Select the empty element and add New Item. Under General category, select Resources File. After the file is created, select it and in Properties change Build Action to Content. Expand Deployment Location and clear the value in Path. Change Deployment Type to AppGlobalResource.

Build Action for Application Resource

To reference a resource string, use the following in your code behinds or classes: 

HttpContext.GetGlobalResourceObject("Softlanding.SharePoint.Global",
"MsgAppGlobalResource").ToString()

where Softlanding.SharePoint.Global is the name of the resource file without the file extension and MsgAppGlobalResource is the resource key I created.

Application Resource File Content

To reference a resource string in application pages and user controls, use the following:

<%$Resources:Softlanding.SharePoint.Global,MsgAppGlobalResourceClient%>

Normally I would html encode the string as well so it would become something like:

<SharePoint:EncodedLiteral runat="server" text="<%$Resources:Softlanding.SharePoint.Global,MsgAppGlobalResourceClient%>" EncodeMethod="HtmlEncode"/>

Just a point of note. User control in Visual Web Parts are compiled. We can always reference resource strings in the ascx.cs code behind and set values to controls like labels or literals declared in the ascx file.  Alternatively we can change the Build Action for Application resources to Embedded Resource. Then in the ascx file, we reference a resource string like:

<%= Softlanding.SharePoint.AppGlobalResources.Softlanding_SharePoint_Global. MsgAppGlobalResourceClient %>

Note the periods in the name of Application resource file are changed to underscores.

Closing

Here is what the final Visual Studio project looks like with the 3 types of resource files added:

Visual Studio Project Solution Package

In my next blog, I will show you how to use resource strings in web part property attributes.