SharePoint defines two kinds of resource files: runtime resources (also called application resources) and provisioning resources. Application resources are used within the normal execution of a SharePoint application. Normal SharePoint execution includes application pages, Web Parts, and controls, as discussed in this chapter. SharePoint also distinguishes between application resources used in normal web applications and those used in Central Administration. Provisioning resources, on the other hand, are used when provisioning elements. You use them within features, site definitions, and list definitions. This means you need to be aware of the deployment and usage scenarios.

Provisioning Resources

Provisioning resources are used to localize solutions. This includes

Resources encapsulate and abstract data from logic and design. This makes sense in larger projects involving many developers. Resources are mainly, but not exclusively, used for localization. Localizing all this data can be a challenging task. It makes sense to think about what parts really need to be localized. Remember that in addition to the various kinds of resource files, the localized version requires you to include one file for each supported culture for each of these files. Such projects tend to have an exploding number of files requiring maintenance and deployment.

Resource Locations

Resource files in SharePoint are located in different folders, including these:

The target folder you use depends on what kind of resource you want to deploy. Every type of resource has its own folder. Provisioning resources are part of either a solution package or a feature. They land in these folders:

Every feature uses the resources file located in its Resources folder. You can, however, use another resource file or even shared resources. To share resource files you have to put them in the 14Resources folder. This is the default option that is used when you add an item of type Global Resource File to your current solution. Site definitions and list definitions also get their resources from this folder.

Application resources can appear in these folders:

Application resources are located in the CONFIGResources folder. For a web application to use those resources, they must be copied to their own App_GlobalResources folder. This is standard practice for global resources in any conventional ASP.NET project. On creation of the web application, the resources are initially copied to the App_GlobalResources folder. When you add new resources to the CONFIGResources folder, the resources need to be copied to existing web applications. You can do this manually or use the stsadm command copyappbincontent. Alternatively, you can automate this by including the following in your FeatureActivated event in your feature receiver. For Central Administration resources and site maps, call

SPWebService.AdministrationService.ApplyApplicationContentToLocalServer();

For regular application page resources and site maps, this code snippet applies:

SPFarm.Local.Services.GetValue().ApplyApplicationContentToLocalServer();

For administrative purposes, application resources use different folders. Administrative extensions add UI elements for features to Central Administration, allowing administrators to manage your code. Chapter 17 contains more information regarding these tasks. The appropriate folders are

Application resources for Central Administration work the same way as normal application resources, except that the base folder is CONFIGAdminResources.

Now you need to know how to use resources within SharePoint elements. It doesn't really matter which kind of resource you are using. SharePoint will retrieve the data from any of the resources available through the current context. A global resource for an application page can be read from the current context:

HttpContext.GetGlobalResourceObject("MyResource", "MyName").ToString();

Any property within a markup file can use the expression builder syntax:

<%$Resources:MyResource, MyName%>

For a regular ASP.NET or SharePoint element, this would read

<asp:literal runat="server" Text="<%$Resources:MyResource, MyName%>" />

In XML configuration files (CAML) that SharePoint can read, you use this syntax:

$Resources:MyResource, MyName

In XML features, you use the default resource of the feature and access it like this:

$Resources:MyName

The next section contains a more detailed description of common usage scenarios in Web Parts and application pages.

Static data can be defined at the assembly level and per element or class within an assembly, such as a Web Part class.

Defining a Static Resource per Solution

For static data you need a resource file. Visual Studio 2010 provides an item for this in the General section of the Installed Templates window. Simply add a resource file by using the Resources File project template (see Figure 8-5). The name must be unique within the project. The RESX file is compiled internally into a .resource file and stored in the assembly as part of the metadata. It does not become part of the package or feature definition files.

Figure 8.5. Adding a global resource file from the General tab

Defining a Static Resource per Item

To create a global resource that is dedicated to supporting a specific Web Part within your solution, you can choose the project item template Global Resources File from SharePoint

Figure 8.6. Adding a global resource file from SharePoint

2010 within a Web Part

The result is much the same as with the common resource item—a RESX file. After choosing this template, you'll be asked whether you wish to create a culture-invariant file or a culture-specific file. This simply affects whether a culture shortcut is included within the file name (such as en-us for US culture) or whether one is omitted altogether.

SharePoint has its own resource management. This does not prevent you from using the common ASP.NET model, but it's useful to know what the differences are and why they exist. If you add a global resource file to any item in the project, Visual Studio adds the resource to the package at a global level. That's confusing, as the relative path to the file in the solution does not match the position in the SharePoint root. Moreover, resources that are created for SharePoint this way are not compiled. They become part of the package as original files. They are deployed to the Resources folder directly under the 14TEMPLATE folder. Let's examine first how this works internally before looking into modification options.

When you add a global resource file, it is assigned the deployment type RootFile and placed directly under 14TEMPLATEResources, as shown in Figure 8-7.

Figure 8.7. SharePoint resources are deployed as is to a special folder.

In the package this looks like this:

<Solution ...>
   <RootFiles>
      <RootFile Location="ResourcesVisualGlobalResource.resx" />
   </RootFiles>
</Solution>

Changing the properties of the file changes the package definition, too. There are good reasons that this is the case. Placing all files into the root can cause naming conflicts with other packages. Such resources are accessible through the resource expression builder syntax. You may be familiar with the $Resources: core... snippets, which access the internal resources. The core.resx file, together with the installed language packs, is stored in the Resources folder, too. Consequently, you can access your own global resource files the same way from any markup file, including visual Web Parts and ASPX application pages, and within CAML markup files.

Using Static Resource Files

After choosing either template, you can assign the file to a specific culture, or leave it culture invariant. If you simply wish to store static data, use the invariant culture. Once added, you can edit the file with the resource editor. Alternatively, use the XML editor to edit the data directly.

You can access the resources from markup using expressions if you create a visual Web Part. That uses expressions based on the Resources expression builder:

<%$ Resources:StaticResources,Help.Text %>

The expression must appear within a specific attribute, such as

<asp:label runat="server" Text="<%$ Resources:StaticResources,Help.Text %>" />

The name StaticResources is the resource's file name. Nonvisual (regular) Web Parts don't have any markup. To use the data in code, you can use the ResourceManager of the current Page that is available through any Web Part.

Using resources for localization requires some preliminary work, as described in the following exercise.

The RESX files are similar to the following XML snippet (the schema and type definition have been omitted for clarity):

<data name="Button.Text" xml:space="preserve">
    <value>Click me</value>
</data>
<data name="Button.Tooltip" xml:space="preserve">
    <value>Click me tooltip</value>
</data>

The following code can be used to retrieve the resource:

protected override void CreateChildControls()
{
   Button b = new Button();
   ResourceManager rm = new ResourceManager("Apress.SP2010.WebParts.
                                             ResourceWebPart.NonVisualWebPart",
                                                  this.GetType().Assembly);
   b.Text = rm.GetString("Button.Text");
   b.OnClientClick = "ShowAlert(this)";
   Controls.Add(b);
   base.CreateChildControls();
}

The ResourceManager class is defined in the System.Resources namespace and stored in the System.Configuration.dll assembly, which must be referenced in the project. The resource manager requires a string that defines the full name to the embedded resource. As shown in Figure 8-8, you can attach RESX files directly to the Web Part itself (the first constructor call of ResourceManager) or use any folder structure that's appropriate (the second call; rm2).

Figure 8.8. The name of the resource is built from the namespace, path, and file name.

The GetString method uses the current culture, if one is specified, to retrieve the correct resource. There is an overloaded GetString method that also accepts a CultureInfo object to force a specific culture.

If you are building a reusable Web Part, localization for the content is straightforward, as shown previously. However, localizing the attributes is not supported the same way. In all the previous examples, the strings were hard-coded:

[WebBrowsable]
[Category("Look and feel")]
[WebDisplayName("Use custom palette")]
[WebDescription("Check this to use a custom palette")]
[Personalizable(PersonalizationScope.Shared)]
public bool UseCustomPalette {
   get;
   set;
}

All these attribute values are hard-coded into your assembly, and you have to build different assemblies for different languages. Fortunately the .NET Framework is extensible, allowing these attributes (Category, WebDisplayName, and WebDescription) to be extended to take advantage of the localization features. To do so, create derived classes, such as LocalizedCategoryAttribute, LocalizedWebDisplayNameAttribute, and LocalizedWebDescriptionAttribute.

They essentially look the same. Code for the LocalizedWebDisplayNameAttribute looks like this:

[AttributeUsage(AttributeTargets.Property, AllowMultiple = false, Inherited = true)]
public sealed class LocalizedWebDisplayNameAttribute
    : WebDisplayNameAttribute
{

     bool m_isLocalized ;

     public LocalizedWebDisplayNameAttribute(string displayName)
         : base(displayName)
     {
     }

     public override string DisplayName
     {
         get
         {
             if (!m_isLocalized)
             {
                 this.DisplayNameValue =
                     Resources.ResourceManager.GetString(
                         base.DisplayName, Resources.Culture);
                 m_isLocalized = true;
             }
             return base.DisplayName;
         }
     }
}

To change the attributes' behavior, this code overrides the DisplayName property; and instead of only returning the value, it uses the ResourceManager object to retrieve the value from your localized resources. Subsequently, you can change the original property code to something like this:

[WebBrowsable]
[LocalizedCategory("LookAndFeel")]
[LocalizedWebDisplayName("UseCustomPalette")]
[LocalizedWebDescription("UseCustomPaletteDesc")]
[Personalizable(PersonalizationScope.Shared)]
public bool UseCustomPalette
{
   get;
   set;
}

To make this work, simply add the three attribute values (LookAndFeel, UseCustomPalette, and UseCustomPaletteDesc in this example) to resource files—one for each language you want support.

In addition to the resources retrieved from an assembly, some elements of an HTML page may require file-based data. JavaScript files are usually linked this way. Assuming your Web Part needs some custom JavaScript, it makes sense to hold it in a separate file. The browser caches this file, and if the Web Part is added several times, the script is only loaded once.

ASP.NET has a concept dedicated to this situation, called web references. Similar to the resources explained previously, web references add resources to the project's assembly. These resources are global, and there is a specific way to call them directly using an HTTP GET request. There is a handler responsible to resolve such calls. The handler is bound to the file name WebResource.axd. In HTML, such a call would look like this:

<script src="WebResource.axd?d=SbXSD3uTnhYsK4gMD8..." />

The unique parameter d provided in the request is built dynamically during the render process. Additionally, a time stamp using the parameter t can be set to allow the resource to time out. This happens when a new assembly is built, to force reloading of the cache.

To support the web resource, you need to prepare the project with the steps shown in the following exercise.

PREPARING WEB RESOURCES

1. Note the namespace of your project.

2. Add your resources in a dedicated folder, such as /Resources/Alert.js.

3. Right-click your resource file and set Build Action to Embedded Resource, as shown in Figure 8-9.

4. Add the following code line in the AssemblyInfo.cs file (replace NameSpace with the namespace of the project, as noted in step 1):

   [assembly: System.Web.UI.WebResource("NameSpace.Resources.Alert.js",
                                        "text/javascript")]

5. Recompile the project.

Figure 8.9. Set the Build Action property to add the file to the assemblies manifest.

The file is now part of the assembly and can be used using the WebResource.axd syntax.

To use the file, you must retrieve the ID that's created dynamically for each request. Depending on what kind of file is used, you need to add the appropriate HTML element to your Web Part. The next example uses a simple JavaScript file. It adds a button dynamically to the Web Part and invokes a method in that file. First, here's the JavaScript snippet that's responding to the button's click:

function ShowAlert(val) {
    alert("Value: " + val);
}

The Web Part itself makes use of the embedded resource, as shown in Listing 8-2.

using System;
using System.Runtime.InteropServices;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;

namespace SimpleWebPart.ResourceWebPart
{
    public class ResourceWebPart : WebPart
    {
        public ResourceWebPart()
        {
        }

        protected override void OnInit(EventArgs e)
        {
            base.OnInit(e);
            string script = "Apress.SP2010. 

                             ResourceWebPart.NonVisualWebPart.MyResources. 

                             Alert.js";
            if (!Page.ClientScript.IsClientScriptBlockRegistered(script))
            {
                Page.ClientScript.RegisterClientScriptResource(this.GetType(), 

                                                               script);
            }
        }

        protected override void CreateChildControls()
        {
            Button b = new Button();
            b.Text = "Click me!";
            b.OnClientClick = "ShowAlert(this)";
            Controls.Add(b);
            base.CreateChildControls();
        }

    }
}

The script variable contains the string defined in the AssemblyInfo.cs file shown in the previous instruction. The code registers a script block on the page and ensures that the script is linked only once. When you now build, deploy, and add the Web Part to a page, the HTML code is produced and creates the output shown in Figure 8-10.

Figure 8.10. A Web Part using embedded resources in the page's edit view

The resource manager loads the resources from files and retrieves the desired element for a specific culture. A culture is a combination of a country and a language. The country defines the currency—for instance, while the language defines the number format and month names. Several types can be formatted dynamically using different cultures. Cultures are defined in a language-country format, such as En-Us or De-de. Cultures form a hierarchy. If the current culture is not found (e.g., De-de), then the resource manager tries to fall back to the parent—De in this case. If this fails, a default resource is used instead. If there is no default resource, an exception is thrown.

The explicit usage of file-based resources is not the common way to provide such additional data. However, under specific circumstances it may make sense to have resources distributed separately. Adding the files as a module to the package makes the deployment easier. Extracting the data from those files requires two steps:

The resource manager reads the contents of the .resources files (compiled RESX files) and provides instant access:

System.Resources.ResourceManager rm;
rm = ResourceManager.CreateFileBasedResourceManager("Global", "ResourceDir", null);
lbl.Text = rm.GetString("Help.Text");

The parameters require a base name as the first parameter—usually the name of the compiled file. If the file name is Global.en-us.resx, then it compiles to Global.en-us.resources (the base name is Global). The resource manager is smart enough to look for all files of that name in the target folder (ResourceDir) whether or not they have a culture segment in their name. The resulting type is ResourceSet by default—that's what the third parameter specifies. In advanced scenarios you could create a type that behaves differently here in the way it is reading the resources. If set to null the default type is used. The resource manager accesses resources by their key, using the GetString or GetObject method. In the case of an object, you need to determine the type and cast the returned value appropriately.

A feature can contain items published to the configuration database (e.g., lists, data, and event receivers). It cannot contain elements copied to a target folder. These items must be part of the package. In the example, the navigation is defined in a web.sitemap file that is common for ASP.NET projects. To edit it easily, you can add an XML file to the current project and name it web.sitemap. Then add the correct schema to it, and IntelliSense will support you (see Figure 8-15).

Figure 8.15. Add the appropriate schema to get IntelliSense.

Once IntelliSense is operating you can edit the file, as shown in Figure 8-16.

Figure 8.16. Editing an embedded XML file using the schema

The web.sitemap file in this example is embedded in the assembly by setting Build Action to Embedded Resource. This makes deployment easier and prevents users from modifying the contents.

Next, the feature receiver can be added to the project. Listing 8-3 shows the complete code.

using System;
using System.Runtime.InteropServices;
using System.Security.Permissions;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Security;
using Microsoft.SharePoint.Navigation;
using System.Xml.Linq;
using System.Linq;
using System.IO;
using System.Xml;
using Microsoft.SharePoint.Utilities;

namespace ApplicationPage.Features.Feature1
{
    [Guid("9f3e821a-1e27-425f-b3f6-93a2847f6544")]
    public class Feature1EventReceiver : SPFeatureReceiver
    {

        string PATH = @"/_layouts/";

        public override void FeatureActivated(
                             SPFeatureReceiverProperties properties)
        {
            if (properties.Feature.Parent is SPSite)
            {
                // Cannot activate this feature at site level
                return;
            }
            SPWeb web = (SPWeb)properties.Feature.Parent;
            SPNavigationNodeCollection topNavi = web.Navigation.TopNavigationBar;
            // Check existing top element. If present remove first
            CheckAndRemove(topNavi);
            // Read navigation instruction
            using (Stream st = GetType().Assembly.
                         GetManifestResourceStream("ApplicationPage.web.sitemap"))
            {
                using (XmlReader tr = new XmlTextReader(st))
                {
                    try
                    {
                        XElement siteMap = XElement.Load(tr);
                        // Add nodes
                        var root = from r in siteMap.Descendants()
                                   where r.Attribute("title").
                                           Value.Equals("HR Department")
                                   select r;
                        // Found
                        if (root.Count() == 1)
                        {
                            XElement rootElement = root.First();
                            string rootPath = web.Url + PATH;

                            // Create and add root node
                            SPNavigationNode rootNode = new SPNavigationNode(
                                rootElement.Attribute("title").Value,
                                rootPath + rootElement.Attribute("url").Value,
                                true);
                            SPNavigationNode topNode = topNavi.AddAsLast(rootNode);
                            AddNodes(rootElement, topNode, rootPath);

                        }
                    }
                    catch (Exception ex)
                    {
                    }
                }
            }
        }

        private void AddNodes(XElement currentFrom, SPNavigationNode currentTo,
                               string rootPath)
        {
            foreach (XElement r in currentFrom.Elements())
            {
                SPNavigationNode n = new SPNavigationNode(
                                         r.Attribute("title").Value,
                                         rootPath + r.Attribute("url").Value);
                SPNavigationNode newnode = currentTo.Children.AddAsLast(n);
                if (r.HasElements)
                {
                    AddNodes(r, newnode, rootPath);
                }
            }
        }

        private void CheckAndRemove(SPNavigationNodeCollection topNavi)
        {
            var nodes = from n in topNavi.Cast<SPNavigationNode>()
                        where n.Title.Equals("HR Department")
                        select n;
            if (nodes.Count() == 1)
            {
                topNavi.Delete(nodes.First());
            }
        }

        public override void FeatureDeactivating(
                             SPFeatureReceiverProperties properties)
        {
            SPWeb web = (SPWeb)properties.Feature.Parent;
            SPNavigationNodeCollection topNavi = web.Navigation.TopNavigationBar;
            CheckAndRemove(topNavi);
        }

    }
}

This code checks first whether the parent object is an SPSite or SPWeb. This feature receiver supports SPWeb only, and therefore does nothing if SPSite appears. This is because there is no navigation object at the site level. You should set the feature's properties appropriately, as shown in Figure 8-17.

Figure 8.17. Set the right scope for the feature to have access to scope-specific data.

There are two private methods to create the node collection and remove it later. The creation method is recursive to allow for an unlimited number of node levels. The elements in Top Navigation and Quick Launch are SPNavigationNode objects. These objects require valid paths before being added to the parent node's collection. The URL is set to the URL of the current web, and the _layouts folder is hard-coded. This example also assumes that the root folder is named HRDepartment, and even this is hard-coded. You can easily extend the code to be more flexible. The options available for the navigation are explained in more detail in Chapter 10.

The feature you deploy must contain the information about the receiver. This requires two settings:

If you create the feature and feature receiver as explained previously using Visual Studio 2010, the necessary information is built automatically. If you plan to create your feature's manifest file manually or edit it later, you will need to define this information. Such a file looks like this:

<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
         Title="ApplicationPage Add Menuitems"
         Id="4e8fed7b-0acf-48f9-9b60-4584b5bcd4bc"
         ReceiverAssembly="ApplicationPage, Version=1.0.0.0, Culture=neutral,
                           PublicKeyToken=791a6f2c4cde1076"
         ReceiverClass="ApplicationPage.Features.Feature1.Feature1EventReceiver"
         Scope="Web">
</Feature>

The ReceiverAssembly and ReceiverClass tags must be set to the appropriate values. The receiver class entry must define the whole namespace. The feature itself may be used only to transport the event receiver information—meaning that you can leave it empty if you don't have anything to add there.

The feature.xml file has several more properties that also influence the receiver:

Please refer to Chapter 9 to read more about the various settings.

The event receiver manifest file elements.xml controls this behavior. An example is shown in Listing 8-4.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Receivers >
    <Receiver>
      <Name>SiteEventReceiverWebDeleting</Name>
      <Type>WebDeleting</Type>
      <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
      <Class>WebProvisioning.SiteEventReceiver.SiteEventReceiver</Class>
      <SequenceNumber>10000</SequenceNumber>
    </Receiver>
    <Receiver>
      <Name>SiteEventReceiverWebAdding</Name>
      <Type>WebAdding</Type>
      <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
      <Class>WebProvisioning.SiteEventReceiver.SiteEventReceiver</Class>
      <SequenceNumber>10000</SequenceNumber>
    </Receiver>
    <Receiver>
      <Name>SiteEventReceiverWebProvisioned</Name>
      <Type>WebProvisioned</Type>
      <Assembly>$SharePoint.Project.AssemblyFullName$</Assembly>
      <Class>WebProvisioning.SiteEventReceiver.SiteEventReceiver</Class>
      <SequenceNumber>10000</SequenceNumber>
      <Synchronization>Synchronous</Synchronization>
    </Receiver>
  </Receivers>
</Elements>

For elements that support asynchronous behavior, you can force a synchronous call by using the <Synchronization> element. The receiver itself needs the assembly where the class is stored, the full class name including the namespace, a name that's used internally only, and the type, which is the internal event name listed in the preceding bullet points.

If there are several event handlers attached to the same event, you can use the sequence number element to define the order. If you create the file using Visual Studio 2010, the $SharePoint.Project.AssemblyFullName$ placeholder is used to reference the current project's assembly. If you create the file manually, you must enter the fully qualified assembly name in the <Assembly> element.

The event receiver for sites and webs is defined in the Microsoft.SharePoint.SPWebEventReceiver class. The example in Listing 8-5 modifies the title of the created site after provisioning.

using System;
using System.Security.Permissions;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Security;
using Microsoft.SharePoint.Utilities;
using Microsoft.SharePoint.Workflow;

namespace WebProvisioning.SiteEventReceiver
{

    public class WebEventReceiver : SPWebEventReceiver
    {

       public override void WebDeleting(SPWebEventProperties properties)
       {
           try
           {
               if (properties.Web.Lists["Data"] != null)
               {
                   properties.Cancel = true;
               }
           }
           catch
           {
           }
           base.WebDeleting(properties);
       }

       public override void WebAdding(SPWebEventProperties properties)
       {
           base.WebAdding(properties);
       }

       public override void WebProvisioned(SPWebEventProperties properties)
       {
           properties.Web.Title += String.Format(" [Created By: {0}]",
                                   properties.UserDisplayName);

properties.Web.AllowUnsafeUpdates = true;
           properties.Web.Update();
           base.WebAdding(properties);
       }

    }
}

The code simply adds the current user's full name (including the domain) to the site's title (see Figure 8-19). In the web-deleting event it tries to prevent the action from being processed if a list named Data still exists. This is a common technique to prevent users from accidentally removing a site along with crucial data. Imagine backing up this data before the user will be able to remove the site and all containing lists. To abort the process, simply set the Cancel property to true.

Figure 8.19. A site title modified by a site collection feature's web event receiver

If you don't want to let users deactivate a feature that's dedicated to such basic tasks, you can set the feature state to "hidden." While it is invisible, it is still working. When the feature is deployed as a solution, normally administrators will still be able to remove the solution to deactivate and remove the feature.

The cancellation of the web deletion is probably not obvious to the user, because from their perspective nothing happens. You can write to the event log or in some private log, but an end user with limited rights is unlikely to access either of those. To force SharePoint to display a message, you can throw an exception, as demonstrated in the following modified WebDeleting method:

public override void WebDeleting(SPWebEventProperties properties)
{
   try

{
      if (properties.Web.Lists["Data"] != null)
      {
         properties.Cancel = true;
       }
    }
    catch
    {
        throw new SPException("Cannot delete the site because it
                                has user data in it");
     }
     base.WebDeleting(properties);
}

Now the exception is caught at a higher level and presented via an error message box. (It's not very aesthetic, but the text is communicated (see Figure 8-20).

Figure 8.20. A slightly customized error message

The exception aborts the procedure internally, so you don't need to explicitly set the Cancel property.

In previous chapters we explained how to raise the access rights by elevating privileges. It makes sense to encapsulate this in a method that returns an elevated web, as shown in Listing 8-9. Note that the caller is responsible for disposing the object afterward to free up memory properly.

public static SPWeb GetElevatedWeb()
{
    SPWeb web = null;
    try
    {
        SPSecurity.RunWithElevatedPrivileges(
            () =>
            {
                if (SPContext.Current != null)
                {
                    using (SPSite site = new SPSite(SPContext.Current.Web.Url))
                    {
                        web = site.OpenWeb();
                    }
                }
            });
    }
    catch
    {
        if (web != null)
        {

web.Dispose();
            web = null;
        }
    }
    return web;
}

The code uses the current context to retrieve the current web and returns the same web with the System Account as the current user.

You can obtain a list instance from the current SPWeb via the Lists property. A custom method results in cleaner code. Listing 8-10 demonstrates one way to make small improvements to simplify the higher-level calling code.

public static SPList GetList(string title, SPWeb web)
{
    return web.Lists.Cast<SPList>().FirstOrDefault(list => list.Title == title);
}

public static SPList GetList(Guid id, SPWeb web)
{
    return web.Lists[id];
}

As well as using either the list's Title or its Guid to get the list instance, you can modify this code to use any other property to select a list, such as RootFolder.Name to use the internal name.

When working with list data you should use a strongly typed data model. With SPMetal you can create a LINQ to SharePoint layer for existing lists. In a distributed environment, however, this is not generally the best solution. A "self-made" data context and a hand-written data model are sometimes better options than using SPMetal. Such a data layer is thin, easy to create, and fast.

First, assume you want to get a list instance, not just as an SPList object, but as something more type-safe. Such a method could look like this:

public static SPList GetList<T>(SPWeb web) where T : BaseSPListItem
{
    return GetList(ApplicationResources.ResourceManager.GetString(typeof(T).Name),
                   web);
}

The GetList call leads to the method shown in Listing 8-11. The lists the application actually uses are stored in an application resource. The crucial thing is the type T and the base class used to constrain the generic. The SPWeb object is used explicitly to allow the caller to decide whether it's a regular object or one with elevated privileges.

Second, the BaseSPListItem class plays a vital role. It encapsulates access to a list item and provides serialization. Serializing SharePoint objects can be messy, because the underlying COM objects prevent you from doing so. The base class in Listing 8-11 uses methods for direct SharePoint object access to avoid serialization. Serializing here means that the object is destroyed on serializing—only the list's ID and item's ID survive. The deserializer calls the default constructor and re-creates the object.

public static class BaseSPListItemFields
{
    public const string ID = "ID";
    public const string UniqueID = "UniqueID";
    public const string Title = "Title";
    public const string Name = "Name";
    public const string Author = "Author";
    public const string Editor = "Editor";
    public const string Created = "Created";
    public const string Modified = "Modified";
}

[Serializable()]
public abstract class BaseSPListItem
{

    private SPListItem _item;

    public SPListItem GetListItem()
    {
        return _item;
    }

    public void SetListItem(SPListItem item)
    {
        _item = item;
    }

    public SPList GetBaseList()
    {
        return _item.ParentList;
    }

    protected BaseSPListItem()
    {
        if (ID != Guid.Empty)
        {
            SPList list = DataManager.GetList(ParentList, SPContext.Current.Web);
            _item = list.GetItemByUniqueId(ID);
        }
    }

    protected BaseSPListItem(SPListItem listItem)
        : this()
    {
        this._item = listItem;
        this.ParentList = _item.ParentList.Title;
        this.ID = _item.UniqueId;

this.ParentWeb = _item.Web.Title;
    }

    public Guid ID
    {
        get;
        set;
    }

    public string ParentList
    {
        get;
        set;
    }

    public string ParentWeb
    {
        get;
        set;
    }

    /// <summary>
    /// Internal ID of the ListItem
    /// </summary>
    public int GetID()
    {
        return _item.ID;
    }

    public Guid GetUniqueID()
    {
        return _item.UniqueId;
    }

    public String Title
    {
        get { return (String)GetValue(BaseSPListItemFields.Title); }
        set { SetValue(BaseSPListItemFields.Title, value); }
    }

    public String Name
    {
        get { return (String)GetValue(BaseSPListItemFields.Name); }
        set { SetValue(BaseSPListItemFields.Name, value); }
    }

    public SPFieldLookupValue GetAuthor()
    {
        return new SPFieldLookupValue(
                   (String)GetValue(BaseSPListItemFields.Author));
    }

    public SPFieldLookupValue GetEditor()
    {

return new SPFieldLookupValue(
                   (String)GetValue(BaseSPListItemFields.Editor));
    }

    public DateTime? GetModified()
    {
        return GetValue(BaseSPListItemFields.Modified) as DateTime?;
    }

    public DateTime? GetCreated()
    {
        return GetValue(BaseSPListItemFields.Created) as DateTime?;
    }

    public virtual void EnsureTitle()
    {

    }

    public object GetValue(Guid fieldID)
    {
        object retVal = null;
        if (_item != null)
        {
            try
            {
                retVal = _item[fieldID];
            }
            catch { }
        }
        return retVal;
    }

public void SetValue(Guid fieldID, object value)
    {
        if (_item != null)
        {
            _item[fieldID] = value;
        }
    }

    public object GetValue(String propertyName)
    {
        object retVal = null;
        if (_item != null)
        {
            try
            {
                retVal = _item[propertyName];
            }
            catch { }
        }
        return retVal;
    }

    public void SetValue(String propertyName, object value)
    {
        if (_item != null)
        {
            _item[propertyName] = value;
        }
    }

    public bool DoesFieldExist(String fieldName)
    {
        return _item.Fields.ContainsField(fieldName);
    }

    public override string ToString()
    {
        StringBuilder sb = new StringBuilder();
        String del = "";
        sb.Append(this.GetType().Name + "[");
        foreach (PropertyInfo pi in this.GetType().GetProperties())
        {
            if (pi.GetGetMethod() != null)
            {
                object obj = pi.GetValue(this, null);
                sb.Append(del + pi.Name + "=" +
                          ((obj == null) ? "NULL" : obj.ToString()));
                del = ", ";
            }
        }
        sb.Append("]");
        return sb.ToString();
    }

    public void Update()
    {
        if (_item != null)
        {
            _item.Update();
        }
    }
    public void UpdateUnsafe()
    {
        if (_item != null)
        {
            using (SPWeb web = this._item.Web)
            {
                bool allow = web.AllowUnsafeUpdates;
                web.AllowUnsafeUpdates = true;
                _item.Update();
                web.AllowUnsafeUpdates = allow;
            }
        }
    }
    public void SystemUpdate()

{
        if (_item != null)
        {
            _item.SystemUpdate();
        }
    }
    public void SystemUpdateUnsafe()
    {
        if (_item != null)
        {
            using (SPWeb web = this._item.Web)
            {
                bool allow = web.AllowUnsafeUpdates;
                web.AllowUnsafeUpdates = true;
                _item.SystemUpdate();
                web.AllowUnsafeUpdates = allow;
            }
        }
    }
    public void Delete()
    {
        if (_item != null)
        {
            _item.Delete();
        }
    }
    public void DeleteUnsafe()
    {
        if (_item != null)
        {
            using (SPWeb web = this._item.Web)
            {
                bool allow = web.AllowUnsafeUpdates;
                web.AllowUnsafeUpdates = true;
                _item.Delete();
                web.AllowUnsafeUpdates = allow;
            }
        }
    }
}

Several methods give direct access to common operations, such as saving and deleting. This is all possible using the "unsafe" operation (AllowUnsafeUpdates).

Using this base class is straightforward. Any class in the data model simply implements this class and adds the field access properties. This can look like Listing 8-12.

public static class RequestListFields
{
    public const string MainCategory = "MainCategory";
    public const string SubCategory = "SubCategory";
    public const string DetailCategory = "DetailCategory";
}

[Serializable]
public class RequestList : BaseSPListItem
{
    public RequestList() : base() { }
    public RequestList(SPListItem listItem) : base(listItem) { }

    public SPFieldLookupValue ParentRequest
    {
        get { return new SPFieldLookupValue(
              base.GetValue(RequestListFields.ParentRequest) as string); }
        set { base.SetValue(RequestListFields.ParentRequest, value); }
    }

    public string MainCategory
    {
        get { return base.GetValue(RequestListFields.MainCategory) as string; }
        set { base.SetValue(RequestListFields.MainCategory, value); }
    }
    public string SubCategory
    {
        get { return base.GetValue(RequestListFields.SubCategory) as string; }
        set { base.SetValue(RequestListFields.SubCategory, value); }
    }
    public string DetailCategory
    {
        get { return base.GetValue(RequestListFields.DetailCategory) as string; }
        set { base.SetValue(RequestListFields.DetailCategory, value); }
    }
}

This is merely a suggestion of how to deal with data. You could also extend existing classes using extension methods to simplify the access.

Sometimes you need to get a list by its internal name. This requires retrieving the complete collection of lists and checking the RootFolder.Name property. Using LINQ makes this easy, and using an extension method hides the implementation from the developer. This method reads the complete collection of lists into memory, but not the lists' items.

public static SPList GetListByInternalName(this SPWeb web, string internalname)
{

return web.Lists.Cast<SPList>().FirstOrDefault(
                                     list => list.RootFolder.Name == internalname);
}

Once you have a list, you can do many things with it and its items. Extending the SPList object is a clever way of encapsulating common operations within simple method calls. The CanCreateItems method checks whether the current user has the appropriate permissions to add items to the list:

public static bool CanCreateItems(this SPList list)
{
    return list != null && (list.EffectiveBasePermissions &
           SPBasePermissions.AddListItems) != SPBasePermissions.EmptyMask;
}

The next two methods perform a similar check to determine whether the user has read or write permissions, respectively:

public static bool CanReadItems(this SPList list)
{
    return list != null && (list.EffectiveBasePermissions &
           SPBasePermissions.ViewListItems) != SPBasePermissions.EmptyMask;
}
public static bool CanWriteItems(this SPList list)
{
    return list != null && (list.EffectiveBasePermissions &
           SPBasePermissions.EditListItems) != SPBasePermissions.EmptyMask;
}

The CanDeleteItems method retrieves all the items of a list as an enumerable collection, enabling you to run LINQ to Object queries against the items. However, use this method with caution, as the entire list is read into memory, even if a subsequent LINQ clause extracts a single item.

public static bool CanDeleteItems(this SPList list)
{
    return list != null && (list.EffectiveBasePermissions &
           SPBasePermissions.DeleteListItems) != SPBasePermissions.EmptyMask;
}

The next method performs a query first and then returns the list of items. This call does not read the complete list in case of GetItemsByFieldEquals. The CAML instructions ensure that it's the fastest way to get a filtered list of items. GetItems does not use any filter, and returns all items.

public static IEnumerable<SPListItem> GetItems(this SPList list)
{
    return list.GetItemsByQuery(String.Empty);
}
public static IEnumerable<SPListItem> GetItemsByFieldEquals(this SPList list,
                                                             string value,
                                                             string field)
{
    var query = new XElement("Where",
                    new XElement("Eq",
                        new XElement("FieldRef",
                            new XAttribute("Name", field)),
                        new XElement("Value", value)
                        )
                    );

return list.GetItemsByQuery(query.ToString(SaveOptions.DisableFormatting));
}

The next method closely corresponds to the previous one, but it uses the Contains operator instead of Eq:

public static IEnumerable<SPListItem> GetItemsByFieldContains(this SPList list, string value, string field)
{
    var query = new XElement("Where",
                    new XElement("Contains",
                        new XElement("FieldRef",
                            new XAttribute("Name", field)),
                        new XElement("Value", value)
                        )
                    );
    return list.GetItemsByQuery(query.ToString(SaveOptions.DisableFormatting));
}

Lookup fields need slightly different treatment. Setting the LookupId="true" attribute ensures that the CAML query works as expected:

public static IEnumerable<SPListItem> GetItemsByFieldLookupId(this SPList list,
                                                               int lookupId,
                                                               string field)
{
    var query = new XElement("Where",
                    new XElement("Eq",
                        new XElement("FieldRef",
                            new XAttribute("LookupId", "true"),
                            new XAttribute("Name", field)),
                        new XElement("Value", value)
                        )
                    );
    return list.GetItemsByQuery(query.ToString(SaveOptions.DisableFormatting));
}

If a simple Eq or Contains operator is inadequate, you can pass a query. The following example accepts CAML as a string:

public static IEnumerable<SPListItem> GetItemsByQuery(this SPList list, string caml)
{
    if (list != null)
    {
        if (list.ItemCount <= Constants.PaginationThreshold)
        {
            SPQuery query = new SPQuery();
            query.ViewAttributes = "Scope="Recursive"";
            query.Query = caml;
            SPListItemCollection items = list.GetItems(query);
            foreach (SPListItem item in items)
            {
                yield return item;
            }
        }
        else

{
            SPQuery query = new SPQuery();
            query.ViewAttributes = "Scope="Recursive"";
            query.Query = caml;
            query.RowLimit = Convert.ToUInt32(Constants.RowLimit);
            do
            {
                SPListItemCollection items = list.GetItems(query);
                foreach (SPListItem item in items)
                {
                    yield return item;
                }
                query.ListItemCollectionPosition = items.ListItemCollectionPosition;
            } while (query.ListItemCollectionPosition != null);
        }
    }
}

This code assumes you have a constant defined in Constants.PaginationThreshold, which determines from what number of items the method starts using paging. (For more information about paging, refer to Chapter 4.)

The following method uses a similar approach to return just one item. If the query returns more items, the first in the collection is taken.

public static SPListItem GetItemByQuery(this SPList list, string caml)
{
    SPQuery query = new SPQuery();
    query.ViewAttributes = "Scope="Recursive"";
    query.Query = caml;
    query.RowLimit = 1;
    SPListItemCollection items = list.GetItems(query);
    return items.Cast<SPListItem>().FirstOrDefault();
}

Creating an item is easy. This extension simply improves code readability:

public static SPListItem CreateItem(this SPList list)
{
    return list.Items.Add();
}

While the methods shown previously create or return items, the subsequent methods deal with existing items. These two methods set and get a value using a field's internal name:

public static void SetValue(this SPListItem item, string internalname, object value)
{
    SPField field = item.Fields.GetFieldByInternalName(internalname);
    item[field.Id] = value;
}
public static object GetValue(this SPListItem item, string internalname)
{
    SPField field = item.Fields.GetFieldByInternalName(internalname);
    return item[field.Id];
}

Getting a lookup value is often a pain, because the object type cannot be cast directly. Instead, a constructor call is required. This is what the GetLookup method encapsulates:

public static SPFieldLookupValue GetLookup(this SPListItem item)
{
    return item != null ? new SPFieldLookupValue(item.ID, String.Empty) : null;
}

Updating an item can either be done by the Update method, which sets the current user and processes attached workflows and events, or by SystemUpdate, which internally sets the system account and suppresses security validation on GET requests. Quite often, internal checks need to be suppressed, and to do so the AllowUnsafeUpdates property must be set to true.

public static void UpdateUnsafe(this SPListItem item)
{
    if (item != null)
    {
        bool allow = item.Web.AllowUnsafeUpdates;
        item.Web.AllowUnsafeUpdates = true;
        item.Update();
        item.Web.AllowUnsafeUpdates = allow;
    }
}

public static void SystemUpdateUnsafe(this SPListItem item)
{
    if (item != null)
    {
        bool allow = item.Web.AllowUnsafeUpdates;
        item.Web.AllowUnsafeUpdates = true;
        item.SystemUpdate();
        item.Web.AllowUnsafeUpdates = allow;
    }
}
public static void DeleteUnsafe(this SPListItem item)
{
    if (item != null)
    {
        bool allow = item.Web.AllowUnsafeUpdates;
        item.Web.AllowUnsafeUpdates = true;
        item.Delete();
        item.Web.AllowUnsafeUpdates = allow;
    }
}

The two extension methods shown next are simplifications for lazy coders. They replace the LookupId and LookupValue properties of the SPFieldLookupValue type with Id and Value properties:

public static int Id(this SPFieldLookupValue lookup)
{
    return lookup != null ? lookup.LookupId : 0;
}
public static string Value(this SPFieldLookupValue lookup)
{
    return lookup != null ? lookup.LookupValue : String.Empty;

}

Caching is a common technique to avoid unnecessary calls to a database. The previous examples showed that it is possible to extend SharePoint types to support LINQ to Objects. Remember that this will consume a lot of memory if you have very large lists. Most projects do not have more than a few thousand items in a list, and with a dozen gigabytes of memory or more available on a server, it seems a good idea to store lists in RAM. Using the Cache object, the requested data is shared between the users, and the list is retrieved once only.

public static class LinqCacheExtensions
{
    public static IEnumerable<T> Cache<T>(this IEnumerable<T> source,
                                           string key,
                                           DateTime absoluteExpiration)
    {
        var items = HttpRuntime.Cache.Get(key) as List<T>;
        if (items == null)
        {
            items = source.ToList();
            HttpRuntime.Cache.Add(key, items, null, absoluteExpiration,
                                  System.Web.Caching.Cache.NoSlidingExpiration,
                                  CacheItemPriority.Normal, null);
        }
        foreach (var item in items)
        {
            yield return item;
        }
    }

    public static IEnumerable<T> Cache<T>(this IEnumerable<T> source, string key,
                                          TimeSpan slidingExpiration)
    {
        var items = HttpRuntime.Cache.Get(key) as List<T>;
        if (items == null)
        {
            items = source.ToList();
            HttpRuntime.Cache.Add(key, items, null,
                                  System.Web.Caching.Cache.NoAbsoluteExpiration,
                                  slidingExpiration,
                                  CacheItemPriority.Normal, null);
        }
        foreach (var item in items)
        {
            yield return item;
        }
    }
}

A LINQ query that uses the Cache<T> method will be cached using the HttpRuntime.Cache store. The method extends IEnumerable, a type that the method GetItemsByQuery will return, for example.