You may be wondering why you should bother programming things you can already program using Central Administration or the Site Settings dialogs. Besides, many scripting tasks are better accomplished with stsadm or PowerShell.

There are several good reasons for automating certain tasks using the API. For one, stsadm does not provide a UI. As a scripting tool, it's extremely powerful; however, if you perform an operation repeatedly, it's hard to process return values, error prompts, success messages, and so forth, and assemble a useful report from them all. Even Central Administration is suboptimal if you want to create hundreds of sites or, for example, provision a Web Part to 1,500 existing web sites, each with a slightly different setting.

There are several more advantages of using the API as well. Sooner or later you will start writing site templates for your installation. Customized site templates allow users to build enterprise-specific sites with special features for fulfilling certain tasks. Creating, maintaining, and deploying site templates is challenging work. It is not best practice to customize existing templates. Internally, SharePoint holds the definition of the templates in the database. Your customized version of such an STP file is merely a collection of changes. At runtime, the server merges the existing template with your data (i.e., a merge between content from the database and the file system). As you might imagine, this process can take time. In addition, your definitions may grow unexpectedly. Imagine you need to add a few simple definitions to the onet.xml file, each requiring hundreds of lines. Five additional definitions and a few requirements later, and you face 3,000 lines of XML.

When developers first consider SharePoint, the XML-based configuration seems to be a boon. With IntelliSense, editing such files seems to be a task that even those who don't speak C# fluently could manage. However, sooner or later, depending on how quickly new requirements are added, your solution becomes unworkable.

The answer to all this is the SharePoint API and the deployment framework. The deployment framework consists of two major parts—solutions and features. Solutions contain the distributed parts, assemblies, XML files, resources, and data. A feature is similar to a solution and frequently distributed as a solution. However, it has several ways it can be managed by the SharePoint UI. Users with administrative privileges can activate and deactivate features. The developer of the feature can run code whenever it's activated or deactivated. The feature runs inside SharePoint and has full access to the API.

There are, though, some administrative tasks that are beyond the scope of a feature. For instance, if you wish to configure a farm or create a new web site, you can't use a feature, because features are designed to run inside an already existing site. In those situations, the administrative tasks require a standalone solution. Despite the availability of the stsadm program, or the PowerShell equivalent—and both are adept for such tasks—a more interactive approach would be an advantage. Besides, despite the vast number of features stsadm provides, it still lacks support for some of the tasks you may eventually need. Again, this is where again the SharePoint API appears to be the most flexible and powerful option.

Large SharePoint installations typically include multiple servers. Often they are configured to form a farm, while other installations may require separate servers. To distribute templates among your computing center, automation tasks are essential.

The SPFarm object is one key entry point into the object model. For administrative tasks, the code to obtain an SPFarm object looks like this:

SPFarm farm = SPWebServices.AdministrationService.Farm;

Given an SPFarm object, you can now undertake the necessary tasks. To create and maintain a web, use the SPWebApplicationBuilder class. Running its Create method, an SPWebApplication object is returned, which gives you further access to the freshly created web. The example shown in Listing 17-1 reveals how to construct a new web. It consists of a simple console application with fixed values that performs the creation. Consider using parameters in real life applications.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Microsoft.SharePoint.Administration;

namespace Apress.SP2010.NewWeb
{
    class Program
    {
        static void Main(string[] args)
        {
            string WebName = "Test";   // Change before execute
            int port = 999;                          // Change before execute
            SPFarm farm = SPWebService.AdministrationService.Farm;
            SPWebApplicationBuilder builder = new SPWebApplicationBuilder(farm);
            builder.ApplicationPoolUsername = "Administrator";
            builder.ApplicationPoolPassword = new System.Security.SecureString();
            builder.ApplicationPoolPassword.AppendChar('S'),
            builder.ApplicationPoolPassword.AppendChar('h'),
            builder.ApplicationPoolPassword.AppendChar('a'),
            builder.ApplicationPoolPassword.AppendChar('r'),
            builder.ApplicationPoolPassword.AppendChar('e'),
            builder.ApplicationPoolPassword.AppendChar('P'),
            builder.ApplicationPoolPassword.AppendChar('o'),
            builder.ApplicationPoolPassword.AppendChar('i'),
            builder.ApplicationPoolPassword.AppendChar('n'),
            builder.ApplicationPoolPassword.AppendChar('t'),
            builder.ApplicationPoolPassword.AppendChar('2'),
            builder.ApplicationPoolPassword.AppendChar('0'),
            builder.ApplicationPoolPassword.AppendChar('1'),
            builder.ApplicationPoolPassword.AppendChar('0'),
            builder.ApplicationPoolId = String.Format("AppPool_{0}", WebName);
            builder.DatabaseName = String.Format("SPContentDB_{0}", WebName);
            builder.Port = port;
            builder.Create();
        }
    }
}

When you deal with administrative tasks, you will frequently need to assign passwords. This is a critical aspect, as unencrypted passwords in code create a security hole. For this reason, the SharePoint API forces you to use System.Security.SecureString when handling passwords. This class ensures that the password values cannot be extracted from the memory while your code is running. However, if an attacker gets the compiled code, storing passwords in the code does not hide it. If you're wondering how someone could get access to your highly secured enterprise network, remember that several people—administrators, developers, and managers—may have access to the servers on which your code is running, or at least to the development machines. Also, your code could spread over time and eventually slip into an unsecured domain. You must ensure that your passwords remain completely secure. So, while the following code may look smart, it's actually quite dangerous from a security standpoint:

string password = "SharePoint2010";
foreach (char c in password)
{
    builder.ApplicationPoolPassword.AppendChar(c);
}

The variable password is now in memory, and as long as the garbage collector doesn't clean up this section of memory, the string is readable from a sniffer tool. This might sound not obvious, but it's a common method if the sources and assemblies are not reachable.

Another issue is with the various GUIDs SharePoint uses. You must either reference the right GUID or create a new one. In code, you can generate a new GUID easily in one line:

Guid guid = Guid.NewGuid();

To check what GUIDs already exist, ask the configuration database. (See the section "Retrieving the Configuration Database" near the end of this chapter for more details.)

Having created a new SPWebApplication object, the next step is to configure it. Once you have made all your configuration changes to the new SPWebApplication, call the Update method to persist the settings and update the server farm.

Large enterprises require an amazing number of site collections. Imagine a company with dozens of divisions split into hundreds of independent departments. Each department can run one or more site collections for its specific purpose. The management of hundreds of site collections is a challenging task for administrators; significantly automating that task saves time and money. Creating site collections programmatically ensures that their internal structures will be well defined and will strictly adhere to the enterprise policies.

For administrative purposes you need to think about automation tasks. Using XML (see Listing 17-2) to define the configuration for an action is a common approach.

<?xml version="1.0" encoding="utf-8" ?>
<SiteDefinition>
  <Url>/sites/BlankInternetSite</Url>
  <Title>Generated Site</Title>
  <Description>This site is being genereated by a script.</Description>
  <LCID>1033</LCID>
  <WebTemplate></WebTemplate>
  <OwnerLogin>Administrator</OwnerLogin>
  <OwnerName>Administrator</OwnerName>
  <OwnerEmail>[email protected]</OwnerEmail>
</SiteDefinition>

A console application—see Listing 17-3—is used to read this file (assuming it's in the same folder as the executable).

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;
using System.Xml.Linq;

namespace Apress.SP2010.CreateSiteCollection
{
    class Program
    {
        static void Main(string[] args)
        {
            System.Environment.ExitCode = CreateSiteCollection();
        }

        private static int CreateSiteCollection()
        {
            try
            {
                string srvUrl = "http://sharepointserve";
                using (SPSite site = new SPSite(srvUrl))
                {
                    // Current collection
                    SPSiteCollection coll = site.WebApplication.Sites;
                    XDocument definition = XDocument.Load("SiteDefinition.xml");
                    XElement root = definition.Element("SiteDefinition");
                    SPSite newSite = coll.Add(
                        root.Element("Url").Value,
                        root.Element("Title").Value,
                        root.Element("Description").Value,
                        Convert.ToUInt32(root.Element("LCID").Value),
                        (String.IsNullOrEmpty(root.Element("WebTemplate").Value) ?
                                        null : root.Element("WebTemplate").Value),
                        root.Element("OwnerLogin").Value,
                        root.Element("OwnerName").Value,
                        root.Element("OwnerEmail").Value
                        );
                    return 0;
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine(ex.Message);
                return 1;
            }
        }
    }
}

The application does not output anything—the return value is merely used to let it run as part of a batch file. After executing this script, which will take a while, you can open the site. If you didn't provide a template, the user will be prompted to select one (see Figure 17-1). (However, this user will have to have an appropriate permission level to do this.)

Figure 17.1. If a site is created without a template, the user will be prompted to choose one.

To provide a valid template, you must use the internal name, as defined in %SharePointRoot%/TEMPLATES/SiteTemplates. The AdventureWorks example template, for instance, has the internal name BLANKINTERNET. In XML, the element would look like this:

<WebTemplate>BLANKINTERNET</WebTemplate>

You can extend this example by investigating the other overloads provided by the Add method of the SPSiteCollection class.

When you create a new site collection, it automatically contains one web site: the root web. However, you can create any number of web sites within the site collection to further structure the content. The main reason to create subwebs is to break role inheritance and assign different permissions to users working with particular webs.

From an object model viewpoint, each web site corresponds to an SPWeb object. You need to provide an existing site collection, represented by an SPSite object, to which your new web site will be added. This solution follows a similar approach to the previous example and uses an XML file to define the parameters.

<?xml version="1.0" encoding="utf-8" ?>
<SiteDefinition>
  <Url>InternetBlog</Url>
  <Title>Generated Site</Title>
  <Description>This site is being genereated by a script.</Description>

<LCID>1033</LCID>
  <WebTemplate>Blog</WebTemplate>
  <UniquePermissions>False</UniquePermissions>
  <ConvertIfThere>False</ConvertIfThere>
</SiteDefinition>

The code assumes that you have a site collection already. (If you have executed the examples in the order they appear in the book, you should have one.)

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Xml.Linq;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;

namespace Apress.SP2010.CreateWeb
{
    class Program
    {
        static void Main(string[] args)
        {
            System.Environment.ExitCode = CreateWeb();
        }

        private static int CreateWeb()
        {
            try
            {
                string srvUrl = "http://sharepointserve/sites/BlankInternetSite";
                using (SPSite site = new SPSite(srvUrl))
                {
                    // Current collection
                    XDocument definition = XDocument.Load("WebDefinition.xml");
                    XElement root = definition.Element("SiteDefinition");
                    SPWeb newWeb = site.AllWebs.Add(
                        root.Element("Url").Value,
                        root.Element("Title").Value,
                        root.Element("Description").Value,
                        Convert.ToUInt32(root.Element("LCID").Value),
                        (String.IsNullOrEmpty(root.Element("WebTemplate").Value) ?
                                        null : root.Element("WebTemplate").Value),
                        Boolean.Parse(root.Element("UniquePermissions").Value),
                        Boolean.Parse(root.Element("ConvertIfThere").Value)
                        );
                    return 0;
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine(ex.Message);

return 1;
            }
        }
    }
}

The XML file references the Blog template. The Url is relative to your current site collection. In the example, the absolute address of the new blog is

http://sharepointserve/sites/BlankInternetSite/InternetBlog/default.aspx

The settings provided by the XML appear in the web, as shown in Figure 17-2.

Figure 17.2. An automatically created blog

Each site includes a property bag, which is widely used internally by SharePoint. However, there is no reason why you cannot also use this property bag to store common settings related to a site. You can regard the bag as an application settings collection, equivalent to what you would normally define in a web.config or app.config file. As in the configuration files, the settings are a collection of key/value pairs.

The properties you use for your own purpose should be clearly distinguishable from those used internally. The best way to achieve this is by adding a unique prefix, such as myprop_. You access the properties through the Properties property of the SPWeb object.

The code shown in Listing 17-6 uses the site collection previously created in this chapter to add a private value to the property bag.

using System;
using System.Collections.Generic;
using System.Collections.Specialized;
using System.Linq;
using System.Text;
using Microsoft.SharePoint;
using System.Collections;

namespace Apress.SP2010.ReadAddModifyProperties
{
    class Program
    {

        const string PREFIX = "myprop_";

        static void Main(string[] args)
        {
            using (SPSite site =
                  new SPSite("http://sharepointserve/sites/BlankInternetSite/"))
            {
                using (SPWeb web = site.RootWeb)
                {
                    foreach (DictionaryEntry entry in web.Properties)
                    {
                        Console.WriteLine("{0} = {1}", entry.Key, entry.Value);
                    }
                    string key = PREFIX + "AutoCreator";
                    if (!web.Properties.ContainsKey(key))
                    {
                        web.Properties.Add(key,
                            String.Format("Created by {0} at {1}",
                            Environment.UserName,
                            DateTime.Now));
                        web.AllowUnsafeUpdates = true;
                        web.Properties.Update();
                    }
                }
            }
            Console.ReadLine();
        }
    }
}

The code displays the existing properties first. To see your new property you must execute the application twice (see Figure 17-3 for the second output). Because this code changes site settings, the AllowUnsafeUpdates property must first be set to true. An additional reset is not required. With the call of the Update method of the Properties collection, the new property is persisted to the site. Calling SPWeb's Update method has no effect here.

Figure 17.3. Adding a custom property

You can now use your custom properties in your code by accessing the Properties collection.

Since SharePoint is built on top of ASP.NET, that means that the distinct configuration method for ASP.NET, the web.config file, plays a pivotal role. As a developer you consider this file part of your project, along with the central web.config file that configures the server, and optionally those sections dedicated to parts of your application. Maintaining, deploying, and reverting configuration file settings are common tasks. Handling the settings in configuration files and providing deployment strategies for them works well for small implementations. However, once your SharePoint farm starts growing, things become more difficult. Not only does the number of settings increase, but the sheer volume of files also makes it hard to find the specific entry to modify for the desired effect. Configuration files form a hierarchy, and the flexible model allows subsequent files to overwrite settings, replacing those added at higher levels. More confusing, settings at higher levels can define themselves as not overwritable to prevent unpredictable changes. The result is that the final values for settings are sometimes hard to explicitly predict, leading to yet another administrative nightmare.

Using the API is much more powerful and opens up the opportunity to confidently maintain configuration settings throughout a farm. Servers added to the farm receive the current settings automatically, and SharePoint ensures that the settings match. In particular, the SafeControl setting, which registers Web Parts as safe to use by end users, can drive you crazy. Whenever a Web Part is deployed, all web.config files in the farm must be updated. Moreover, even a simple change in the version number to get the latest update necessitates changes across the farm. If the Web Part is deployed as part of a feature, either the feature must change the settings, or some manual action must be performed to do so. That's certainly not the picture of an easy-to-administer server farm—missing an obscure step can cause your features to stop working.

The entry point into the web.config configuration is the SPWebConfigModification class. This class is related to SPWebApplication. This means that each web application has its own list of modifications. The SPWebConfigModification class is useful if you have particular entries that you'd like to set. The settings are stored in the content database and applied to existing web.config files. If a new server is added or a new web.config appears, SharePoint ensures that the registered changes are applied automatically. However, for this to happen, there are some preconditions to be met and several aspects to consider:

To change the settings of an existing entry is easy using this class. The addressing of such entries is straightforward—it uses XPath to navigate within the XML—provided you have a working knowledge of XPath. To access an entry, you can start with the following code:

SPWebConfigModification mod = new SPWebConfigModification();

The object created by this expression has several additional options (see Table 17-1).

Some typical scenarios should clarify things. Imagine you want to set the error handling and show all exceptions, instead of a short, meaningless message. The following entry in web.config would do the trick:

<configuration>
   <system.web>
      <customErrors mode="Off">
   <system.web>
<configuration>

You can access this entry and effect this change in code:

private void ExtendErrorSettings()
{
   SPWebApplication web = new SPSite(txtUrl.Text).WebApplication;
   var mod = new SPWebConfigModification();
   mod.Name = "mode";
   mod.Path = "//system.web/customErrors";
   mod.Owner = "WebConfigSettings.aspx";
   mod.Sequence = 0;
   mod.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureAttribute;
   mod.Value = "Off";
   web.WebConfigModifications.Add(mod);
   web.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();
   web.Update();
}

The complete sample code contains a web form that enables you to enter the application's address in a TextBox named txtUrl. The name of the ASPX page is used as the owner's name.

Removing the setting is as straightforward as creating it:

private void RemoveErrorSettings()
{
    SPWebApplication web = new SPSite(txtUrl.Text).WebApplication;
    var coll = from c in web.WebConfigModifications
               where c.Owner.Equals("WebConfigSettings.aspx")
               select c;
    if (coll.Count() > 0)
    {
        for (int i = coll.Count() - 1; i >= 0; i--)
        {
            // Ensure that we remove from end
            SPWebConfigModification mod = coll.ElementAt(i);
            web.WebConfigModifications.Remove(mod);
        }
        // If run outside SharePoint, this line is required
        HttpContext.Current = null;
        web.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();
        web.Update();
    }
}

Here, we use a LINQ statement to retrieve the modifications for a particular owner. The collection's elements are removed immediately, so you can't loop using a foreach statement. Instead, the for loop ensures that the elements are deleted by removing the elements in order from last to first.

The modification process is performed by a timer job, and runs quickly but not immediately. If you call the ApplyWebConfigModifications method several times, you could encounter an exception that says, "A web configuration modification is already running." As a best practice you should aggregate all modifications together and call the method only once. Assembling several settings and deploying them as one feature is an acceptable strategy. Creating a number of separate features is harder work and causes more stress for the system.

The configuration changes are stored in the Objects table of the configuration database. You can retrieve the stored values via the following SQL statement:

SELECT * FROM Objects WHERE Name LIKE 'WebConfigChanges%'

You can find the changes easily. However, the values stored in the database are out of sequence. Instead, it seems like they are stored in the database in descending order based on the SPWebConfigModification.Name property. Changing the Name and Value properties leads to a sequence like this:

Name = "remove[@sequence='" + sequence + "']"
Value = "<remove verb='*' path='*.asmx' />"
Name = "add[@sequence='" + sequence + "']"
Value = "<add verb='*' path='*.asmx' validate='false'
              type='System.Web.Script.Services.ScriptHandlerFactory, "
              + Constants.AJAXExtensionsAssembly + "' />"

The add[@path='*.asmx'] code will always come before the remove[@path='*.asmx'] part, even if you put the remove part in the collection first and give it a lower sequence number.

You can use the Sequence property to resolve this issue. If you increment the sequence number for each change, you can use this as the key to finding the node. This will put in order all items that have the same tag, but still doesn't fix the ordering for items with different tag names. (Plus, adding this extra attribute isn't the cleanest code, either.)