The first and main object of the Server Object Model is the SPFarm class, which represents a reference to an entire SharePoint server farm. This class belongs to the Microsoft.SharePoint.Administration namespace. You can use it to create a fresh new farm from scratch, or you can connect to an existing farm. To create a new farm, you need to invoke one of the many overloads of the public static Create factory method. To connect to an existing farm (the most common scenario), you provide a SQL Server connection string and the farm’s secret passphrase to the public static Open method, which has the following signature:

public static SPFarm Open(SqlConnectionStringBuilder connectionString, SecureString passphrase)

The connection string corresponds to the farm configuration database that is defined while configuring the farm using the SharePoint 2013 Products Configuration Wizard or PowerShell. You can also find it in the system registry at HKLMSoftwareMicrosoftShared ToolsWeb Server Extensions15.0SecureConfigDBdsn. Alternatively, you can connect directly to a local farm using the static property SPFarm.Local.

After obtaining an instance of SPFarm, you can browse and manage servers and services that belong to that farm. For example, you can browse the Servers collection to enumerate all the physical servers that belong to the farm as objects of type SPServer. You can browse the Services property, which has the type SPServiceCollection and contains different kinds of services—all sharing a common base class of type SPService. You can examine all the Windows services, which are objects of type SPWindowsService, or you can access the web services, which are of type SPWebService. Every web service is composed of one or more web applications, each with the type SPWebApplication. Browsing objects in the local farm shows a code example that browses for all these kinds of objects in the local farm. Note that you should execute this (and the following) code excerpt in a project that references the Microsoft.SharePoint.dll assembly, and you should also provide a using statement for Microsoft.SharePoint, as well as for Microsoft.SharePoint.Administration.

SPFarm farm = SPFarm.Local;
Console.WriteLine("Here are the servers of the Farm");
foreach (SPServer server in farm.Servers) {
    Console.WriteLine("Server Name: {0}", server.Name);
    Console.WriteLine("Server Address: {0}", server.Address);
    Console.WriteLine("Server Role: {0}", server.Role);
}
foreach (SPService service in farm.Services) {
    Console.WriteLine("---------------------------------------");
    if (service is SPWindowsService) {
        Console.WriteLine("Windows Service: {0}", service.DisplayName);
        Console.WriteLine("Type: {0}", service.TypeName);
        Console.WriteLine("Instances: {0}", service.Instances.Count);
    }
    else if (service is SPWebService) {
        Console.WriteLine("Web Service: {0}", service.DisplayName);
        Console.WriteLine("Type: {0}", service.TypeName);
        Console.WriteLine("Instances: {0}", service.Instances.Count);
        SPWebService webService = service as SPWebService;
        if (webService != null) {
            foreach (SPWebApplication webApplication in 
            webService.WebApplications) {
                Console.WriteLine("Web Application: {0}",
                    webApplication.DisplayName);
                Console.WriteLine("Content Databases");
                foreach (SPContentDatabase db in webApplication.ContentDatabases)   
                {
                    Console.WriteLine("Content Database: {0}", db.Name);
                    Console.WriteLine("Connection String: {0}",
                       db.DatabaseConnectionString);
                }
            }
        }
    }
    else {
        Console.WriteLine("Generic Service Name: {0}", service.DisplayName);
        Console.WriteLine("Type Name: {0}", service.TypeName);
        Console.WriteLine("Instances: {0}", service.Instances.Count);
    }
}

In real life, you do not need to edit a farm’s configuration on a daily basis; however, it is important to know that the Server Object Model enables you to edit it should the need arise. Moreover, sometimes it’s useful to begin browsing your farm topology from the root node (SPFarm) so you can explore the site collections and websites in greater detail. You can also execute the same kind of code from a PowerShell script, if you prefer.

SPSite and SPWeb are fundamental types in the Server Object Model. They represent a site collection and a site, respectively. From a SharePoint perspective, a website (SPWeb) is just a child of a collection of one or more sites (SPSite). As you will see later in this chapter, these classes are the basis for many typical operations in your solutions. Every time you need to access the content of a SharePoint site, you will need to reference its parent SPSite object (the site collection the site belongs to), and then open the corresponding SPWeb instance. To access an SPSite instance, you can create it using one of the available constructors, or you can obtain a reference to it through its parent SPWebApplication instance. Here are the constructors provided for building an SPSite instance:

public SPSite(Guid id);
public SPSite(string requestUrl);
public SPSite(Guid id, SPUrlZone zone);
public SPSite(Guid id, SPUserToken userToken);
public SPSite(string requestUrl, SPUserToken userToken);
public SPSite(Guid id, SPUrlZone zone, SPUserToken userToken);

Using the appropriate constructor, you can reference a site collection by its unique ID, which is a globally unique identifier (GUID), or with a URL that corresponds to a resource published by the site collection. Some of these six overloads of the constructor let you access the site by using a specific zone from the SPUrlZone enumeration, the definition of which is shown in the following:

public enum SPUrlZone {
    Default,
    Intranet,
    Internet,
    Custom,
    Extranet
}

These values correspond to the zones that you can create using the SharePoint administrative tools. Other SPSite constructors accept an SPUserToken instance. The SPUserToken class represents a token for a valid SharePoint user. When you create an SPSite instance using such a token, you can impersonate the user who owns that token rather than the current user. You can import an SPUserToken instance from a previously exported array of bytes, or you can create one from an object that implements the generic System.Security.Principal.IIdentity interface. You would, for example, take advantage of these constructor overloads to execute code on behalf of another user, probably one with elevated privileges.

Browsing for SPSite and SPWeb objects of an object of type SPWebApplication shows a code excerpt that browses all the SPSite and SPWeb instances in a set of SPWebApplication objects. The webService variable in the excerpt references an instance of an SPWebService object, which can be retrieved using the code illustrated in Browsing objects in the local farm.

foreach (SPWebApplication webApplication in webService.WebApplications) {
    Console.WriteLine("Web Application: {0}", webApplication.DisplayName);
    foreach (SPSite site in webApplication.Sites) {
        using (site) {
            Console.WriteLine("Site Collection: {0}", site.Url);
            foreach (SPWeb web in site.AllWebs) {
                using (web) {
                    Console.WriteLine("Web Site: {0}", web.Title);
                }
            }
        }
    }
}

The example in Getting a reference to an SPSite object using its public URL shows how to obtain a reference to an SPSite object using its public URL.

using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
    Console.WriteLine("Current Site URL: {0}", site.Url);
    SPWeb web = site.RootWeb;
    Console.WriteLine("Current Site RootWeb Title: {0}", web.Title);
}

After you have a reference to an SPSite instance, you can browse for the sites contained in the collection, or you can change the configuration of the site collection itself. Table 5-1 lists the main members of the SPSite type, which you will probably use often in real projects, along with a brief description of each member.

An SPSite object is required to obtain access to an SPWeb instance. In fact, the SPWeb class does not have a public constructor. The only way to obtain a reference to a site is through its parent SPSite object, although you can get access to the current website using the SPControl and SPContext types, which will be discussed later, in the “SPControl and SPContext” section. The SPSite class provides the OpenWeb method (see Table 5-1) for this purpose. Getting a reference to an SPWeb instance through its parent SPSite object shows an example of accessing a specific website by using its parent site collection.

using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
    Console.WriteLine("Current Site URL: {0}", site.Url);
    using (SPWeb web = site.OpenWeb("SampleSubSite")) {
        Console.WriteLine(web.Title);
    }
}

Getting a reference to an SPWeb instance through its parent SPSite object uses the SPSite.OpenWeb method, which has the following overloads:

public SPWeb OpenWeb();
public SPWeb OpenWeb(Guid gWebId);
public SPWeb OpenWeb(string strUrl);

public SPWeb OpenWeb(string strUrl, bool requireExactUrl);
public SPWeb OpenWeb(string strUrl, SPSiteOpenWebOptions options);

The first overload opens the lowest-level website, as defined by the URL provided to the constructor of the current site collection. For example, if you created the SPSite instance using the root site URL, you would get a reference to the root website. In contrast, if you created the SPSite instance using a child website URL, you would get a reference to that website. The second overload opens the website using its unique ID. The last three overloads accept the relative URL of the website, which must be exact for the last overload if the requireExactUrl argument is true. In the last overload, you have an option of type SPSiteOpenWebOptions, which allows you the choice of initializing a navigation cache.

You can use an SPWeb reference to navigate the contents of the site or simply to read or change its configuration. You will learn how to manage site contents later in this chapter. Table 5-2 lists some of the main members of the SPWeb type.

One of the most interesting members of this type is the Update method. While working with the Server Object Model, you are reading and changing an in-memory representation of the current object. Thus, any changes you make will not be applied to the database unless you explicitly request the object to persist its state using the Update method. Of course, if you change an in-memory SPWeb instance and do not invoke the Update method, your changes will be lost. This behavior is common for many types in the Server Object Model, including SPWeb, SPList, and SPListItem. Additionally, remember that in a typical SharePoint farm, the database server runs on a separate server, which is not the web front end or the application server where your code will run. Thus, saving the state of an object and invoking the Update method requires crossing the wire.

Modifying the title of an instance of SPWeb shows an example that modifies the Title property of the current website, and then invokes the Update method to confirm the action.

using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
    Console.WriteLine("Current Site URL: {0}", site.Url);
    using (SPWeb web = site.OpenWeb("SampleSubSite")) {
        web.Title = web.Title + " - Changed by code!";
        web.Update();
    }
}

Quite often, you will open an SPSite instance and one of its child SPWeb instances to gain access to the contents of one or more lists. The Server Object Model offers two types that target the concept of SharePoint lists and list items: SPList and SPListItem. SPList corresponds to a single list instance, whether that is a list of items or a document library. SPListItem defines a reference to a specific item of a list. In general, you open the list to extract one or more items, and then work with those items. Browsing the items contained in an SPList instance of an object of type SPWeb shows an example that obtains a reference to a list and then browses its items.

using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
    Console.WriteLine("Current Site URL: {0}", site.Url);
    using (SPWeb web = site.OpenWeb()) {
        SPList list = web.Lists["DevLeap Customers"];
        foreach (SPListItem item in list.Items) {
            Console.WriteLine(item.Title);
        }
    }
}

Browsing the items contained in an SPList instance of an object of type SPWeb extracts an SPList object by using the Lists indexer of the current SPWeb instance, which uses the list Title property as a key. Then it enumerates the contents of the Items collection property of the list instance. The SPList type offers a rich set of members. Table 5-3 shows some of the more important members.

Later in this chapter, the “Lists and Items” section shows how you can take advantage of some of these members in realistic scenarios.

Whenever you use an SPList instance, which corresponds to a document library, you can cast that instance to an SPDocumentLibrary type. This type represents a document library, which is almost the same as the base SPList type, but has a small set of more specific members related to file handling. As an example, an SPDocumentLibrary object provides a collection property through which you can enumerate all the currently checked-out files. When you need to enumerate the files contained in a document library, you can browse the SPListItem elements of the list and access their File property, which is of type SPFile. Browsing the files contained in an SPDocumentLibrary instance of an SPWeb object shows some sample code that browses the files of a document library and displays their name and size in bytes.

using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
    Console.WriteLine("Current Site URL: {0}", site.Url);
    using (SPWeb web = site.OpenWeb()) {
        foreach (SPList list in web.Lists) {
            SPDocumentLibrary library = list as SPDocumentLibrary;
            if (library != null) {
                foreach (SPListItem item in library.Items) {
                    Console.WriteLine("{0} - {1}",
                        item.File.Name,
                        item.File.Length);
                }
            }
        }
    }
}

The SPFile class offers a rich set of members, as shown in Table 5-5.

In the “Document libraries and files” section later in the chapter, you will see how to use some of these members to manage files stored in SharePoint.

Another set of useful types for developing real solutions are the SPGroup and SPUser classes. These correspond to a group and a SharePoint user, respectively, and both inherit from SPPrincipal. The SPPrincipal type ultimately inherits from SPMember. From a security point of view, a set of permissions is assigned to an SPPrincipal object using an SPRoleAssignment class. Thus, you can configure permissions equivalently for a user or for a group, using the same classes and syntax. An SPRoleAssignment object maps an SPPrincipal instance to an SPRoleDefinition instance. SPRoleDefinition is the type that defines a SharePoint permission level. In Part VI you will explore how SharePoint security works internally; for now, all you need is a high-level overview of these types. For example, Browsing role assignments and definitions for an SPWeb instance shows how to enumerate role assignments and role definitions.

using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
    Console.WriteLine("Current Site URL: {0}", site.Url);
    using (SPWeb web = site.OpenWeb()) {
        foreach (SPRoleAssignment ra in web.RoleAssignments) {
            Console.WriteLine("-Member Name: {0}", ra.Member.Name);
            foreach (SPRoleDefinition rd in ra.RoleDefinitionBindings) {
                Console.WriteLine("Permissions: {0}", rd.BasePermissions);
            }
        }
    }
}

When you target an SPUser object with a custom SPRoleAssignment instance, you will probably find the list of the main members of the SPUser type useful. You can see the most important members in Table 5-6.

If you are targeting an SPGroup instance, it will help to know about some of the main members explained in Table 5-7.

These classes can be used to make authorization checks by code, or for managing automation of users and groups. For example, you can add a user to a group inside a custom timer job written using these classes. In the “Groups and users” section later in the chapter, you will see how to write this code.

One last group of types provided by the Server Object Model of SharePoint consists of some infrastructural classes such as SPControl and SPContext. The SPControl type is defined in the Microsoft.SharePoint.WebControls namespace. It is the base class for many SharePoint server controls, and it helps when developing web controls or Web Parts. Aside from its base class role, SPControl provides a small set of static methods, the most useful of which let you retrieve a reference to the current SPSite, SPWeb, or SPWebApplication instances. Here are the signatures of these methods:

public static SPModule GetContextModule(HttpContext context);
public static SPSite GetContextSite(HttpContext context);
public static SPWeb GetContextWeb(HttpContext context);
public static SPWebApplication GetContextWebApplication(HttpContext context);

All of these methods require an HttpContext object instance as their sole input argument.

Another way of obtaining a reference to the current SPSite and SPWeb is to use the SPContext class, which provides a static property named Current that references the current SharePoint context. The current SPContext object gives you direct access to all the most useful information about the current request. Table 5-8 shows the main members offered.

For a complete list of all the available types and members in the Server Object Model, see the full online reference on MSDN, at http://msdn.microsoft.com/en-us/library/ms464984.aspx.

The first and most important hint you need to know is how to correctly release resources while working with objects of the Server Object Model. You can either wait for the .NET Framework to do it for you or release resources manually. Which option you choose is largely determined by how critical those resources are. By default, the .NET Framework employs a nondeterministic release of allocated managed objects, which is based on the garbage collector and provided by the common language runtime (CLR). When an instance of a managed type that you created is no longer used, the garbage collector automatically releases the allocated memory—but at a nondeterministic (unpredictable) time. When the managed object holds references to unmanaged resources—such as window handles, files, streams, database connections, sockets, and so forth—these unmanaged resources will be released only when the garbage collector collects memory. When such unmanaged resources are scarce, are critical, happen to lock physical resources, or use a large amount of unmanaged memory, you’re better off releasing them as soon as possible rather than waiting for the .NET garbage collector. To accomplish this goal, the .NET Framework infrastructure provides the IDisposable interface, which exposes a Dispose method that you should call to explicitly release these unmanaged resources. Here’s the definition of the IDisposable interface:

public interface IDisposable {
    void Dispose();
}

There are many patterns for implementing IDisposable; however, it is beyond the scope of this book to give you full coverage of this topic. To learn more about resource disposal in SharePoint, consult the article “Disposing Objects” on MSDN, at http://msdn.microsoft.com/en-us/library/ee557362.aspx.

For now, suffice it to know that whenever a .NET type implements the IDisposable interface, you should invoke the Dispose method as soon as you no longer need the object. Calling Dispose lets you release unmanaged resources in a deterministic manner.

To invoke Dispose, you should adopt a standard technique, such as one of the following:

Employing the using keyword while working with an SPSite instance to ensure timely disposal of unmanaged resources shows a code excerpt that takes advantage of the using keyword.

using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
    // Work with the SPSite object
}

The compiler converts the using keyword into a try…finally code block, such as the one in Using the try…finally block while working with an SPSite instance to ensure timely disposal of unmanaged resources.

SPSite site = null;
try {
    site = new SPSite("http://devbook.sp2013.local/");
    // Work with the SPSite object
}
finally {
    if (site != null)
        site.Dispose();
}

If you need to catch exceptions that might occur while working with disposable objects, wrap the using block or the try…finally block with an external try…catch block, as shown in Wrapping the using block in an external try…catch block while working with an SPSite instance so it can handle any exceptions.

try {
    using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
        // Work with the SPSite object
    }
}
catch (SPException ex) {
    // Handle exception
}

Writing code this way ensures that any unmanaged resources will be released as soon as they are no longer needed. It also ensures that exceptions can be handled without overloading the environment.

You should apply this technique even when using objects from the SharePoint Server Object Model. For example, the SPSite and SPWeb types both implement the IDisposable interface, and both allocate unmanaged memory. If you do not correctly release SPSite and SPWeb instances, you will probably experience memory leaks, crashes, and frequent application pool recycles because of extra (and unnecessary) memory consumption.

However, you must also be careful, because you should dispose of these types only when you have explicitly created them. For example, Incorrect object disposal through the using keyword illustrates a situation in which you should not dispose of an SPSite instance.

try {
    using (SPSite site = SPControl.GetContextSite(HttpContext.Current)) {
        // Work with the SPSite object
    }
}
catch (SPException ex) {
    // Handle exception
}

In Incorrect object disposal through the using keyword, the SPSite instance is retrieved from the request context through the SPControl type. Thus, you didn’t create it; the internal SharePoint Foundation code did. This means you are not responsible for disposing of it. The same logic applies to SPSite or SPWeb references retrieved from the current SPContext object. In contrast, The correct way to handle objects that do not need to be disposed of explicitly shows you the correct way to write the code.

try {
    SPSite site = SPControl.GetContextSite(HttpContext.Current);
    // Work with the SPSite object
}
catch (SPException ex) {
    // Handle exception
}

For situations in which you create both SPSite and SPWeb instances within the same code excerpt, you should employ nested using keywords, as you can see in many examples in this chapter (such as Browsing role assignments and definitions for an SPWeb instance).

Keep in mind that if you are browsing a collection of SPWeb items—for example, enumerating the AllWebs property of an SPSite object—you are responsible for releasing each single SPWeb instance, as exemplified in Object disposal while iterating collections.

try {
    using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
        // Work with the SPSite object
        foreach (SPWeb web in site.AllWebs) {
            using (web) {
                // Work with the SPWeb object
            }
        }
    }
}
catch (SPException ex) {
    // Handle exception
}

Furthermore, there are types that internally create instances of SPSite or SPWeb that you’ll need to dispose of explicitly. For example, the SPWebPartManager and the SPLimitedWebPartManager classes internally use an SPWeb instance that must be disposed of. These types all implement IDisposable, so you should handle them almost the same way as you do the SPSite and SPWeb types.

A perennially interesting area when developing software solutions is that of exception handling for intercepting code failures. The SharePoint Server Object Model provides a base class named SPException, which is the default exception thrown by the SharePoint Server Object Model and is also the type from which almost every specific SharePoint exception inherits. While handling exceptions, consider a few suggestions.

First, catch and handle only those exceptions that you anticipate and can manage. In other words, you should avoid simply catching all exceptions using a catch all block or an empty catch block. That way, when an exception that you don’t anticipate occurs, it will bubble up to higher-level code that is able to handle it, if any exists. If the exception is unexpected through the entire stack of the current request, it’s best to let the software crash. (Of course, you would inform the end user in a friendly manner and possibly automatically alert technical support.) That is exactly what SharePoint does by default for unhandled exceptions. Figure 5-2 shows the default error message that SharePoint displays when an unexpected error occurs.

Figure 5-2. The default message that SharePoint 2013 displays when an unexpected error occurs.

The correlation ID (GUID) shown in the message refers to the current request context, which you can use to search for the exception in the SharePoint ULS log. Specifically, search for a row of type Unexpected that contains the correlation ID from the error dialog at the end of the row. That’s where you can find the unhandled exception details and stack trace.

If you decide to catch unexpected exceptions with code of your own (and thereby avoid the default error message), you will probably still want to log/trace the exception by yourself. Logging an exception to the ULS log shows how to manage an unexpected exception by logging it to the ULS log.

try {
    using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
        // Work with the SPSite object
        foreach (SPWeb web in site.AllWebs) {
            using (web) {
                // Work with the SPWeb object
            }
        }
    }
}
catch (SPException ex) {
    // Log exception to ULS
    SPDiagnosticsService.Local.WriteTrace(0, new SPDiagnosticsCategory(
    "My Custom Category", TraceSeverity.Unexpected, EventSeverity.Error),
    TraceSeverity.Unexpected, ex.Message, ex.StackTrace);
}

Logging an exception to the ULS log illustrates that the SPDiagnosticService provides utilities for logging into the ULS log of the local server, through the WriteTrace method.

Working within a transactional environment when manipulating data is a common application need; however, the SharePoint data engine and the SharePoint Server Object Model are not transactional. You cannot rely on them alone to build a transactional system. In fact, SharePoint is not an RDBMS. Data you store in SharePoint lists should not be critical and should not require a transactional environment. If you do need to store information in SharePoint using a kind of transactional behavior, you need something like a compensable system. For example, you can use a Windows Workflow Foundation 4.5 workflow that makes use of a CompensableActivity activity. Let’s see what that means in concrete terms.

Whenever you invoke the Update method for a Server Object Model object (such as SPListItem), SharePoint updates the corresponding data in the target content database. If you change two or more items and you want to update either all or none of them, you must keep track of such changes yourself (in case you need to revert back to the original values if the process fails) because SharePoint doesn’t support this. The same is true when you need to update data on SharePoint or update data using an external resource manager, such as an RDBMS. If you update the SharePoint content database first and then the RDBMS update fails, you will need to manually restore the original content values on the SharePoint side, using some custom code.

If you must have transactional support while managing data stored in SharePoint, you should probably ask yourself whether SharePoint is truly the appropriate place to store that data. Of course, the answer would be no. In such critical cases, you need a transactional RDBMS instead. You can still use SharePoint to present such data to end users, however, by taking advantage of Business Connectivity Services and external lists for this purpose.

To avoid cross-site scripting issues, SharePoint applies a security check whenever you change data through the Server Object Model during HTTP requests. In fact, by default, SharePoint web forms use a form digest control to enforce security. The FormDigest is a hidden field that is sent by SharePoint web forms via HTTP POST, and checked by the security infrastructure on the server. When you make changes to objects by using the Server Object Model during an HTTP GET request, this input field will be missing, so by default SharePoint will throw an exception that looks like this excerpt:

Microsoft.SharePoint.SPException: The security validation for this page is invalid.

Similarly, if you send an HTTP POST request with a missing or invalid FormDigest value, you will receive the same error. This behavior applies only during HTTP requests. Therefore, when you reference the Server Object Model in a class library or a batch tool that runs outside of the ASP.NET pipeline, the security check will not occur. In fact, the check process looks for the HttpContext.Current variable; if it is null, the digest validation will not occur.

With that in mind, if you are developing a webpage that will respond to HTTP GET requests, or a custom web form page that doesn’t inherit from the WebPartPage type and doesn’t use the FormDigest control, you will need to instruct SharePoint to skip the digest validation; otherwise, your code will not work.

To instruct SharePoint to skip the validation, set the Boolean AllowUnsafeUpdates property of the current SPSite or SPWeb object to true. Using the AllowUnsafeUpdates property of the SPWeb type to skip a security check shows an example.

SPWeb web = SPContext.Current.Web
SPList list = web.Lists["DevLeap Customers"];
try {
    web.AllowUnsafeUpdates = true;
    list.Title = list.Title + " - Changed!";
    list.Update();
}
finally {
    web.AllowUnsafeUpdates = false;
}

The code in Using the AllowUnsafeUpdates property of the SPWeb type to skip a security check works with an SPWeb instance provided by the current SPContext instance. It sets the AllowUnsafeUpdates property to true before changing an SPList instance property, and then resets the property to false (its default value) just after invoking the SPList.Update method. To ensure that the AllowUnsafeUpdates property always reverts to its original value, the code uses a try…finally code block.

Conversely, when you develop a custom ASPX page and you want to exploit the security environment provided by SharePoint, you have a couple of choices. You can inherit from WebPartPage, or you can manually include a FormDigest control in your page. In the first case, you simply need to inherit from the Microsoft.SharePoint.WebPartPages.WebPartPage base class, which internally renders a FormDigest control. Then, in your code, you call the utility method SPUtility.ValidateFormDigest() to check the digest when you post the page back to the server. In the latter case, you need to include the Microsoft.SharePoint.WebControls.FormDigest control in your page(s), and you still need to invoke the SPUtility.ValidateFormDigest() method to check the digest.

Of course, in a custom ASPX page, you could also invalidate the security check by setting the AllowUnsafeUpdates property to true. However, that would be both insecure behavior and poor practice.

This first example shows how to create a new site collection in code (see Creating a new site collection).

 
using (SPSite rootSite = new SPSite("http://devbook.sp2013.local/")) {
    SPWebApplication webApplication = rootSite.WebApplication;
    using (SPSite newSiteCollection = webApplication.Sites.Add(
        "sites/CreatedByCode", // Site URL
        "Created by Code", // Site Collection Title
        "Sample Site Collection Created by Code", // Site Collection Description
        1033, // LCID
        15, // Compatibility level (can be 14 for 2010 or 15 for 2013)
        "STS#0", // Web Site Template for a Team Site
        "SP2013\PaoloPi", // Owner Login
        "Paolo Pialorsi", // Owner DisplayName
        "[email protected]", // Owner EMail
        "SP2013\MarcoR", // Secondary Contact Login
        "Marco Russo", // Secondary Contact DisplayName
        "[email protected]", // Secondary Contact EMail
        "SP2013SQL", // Database Server Name for Content Database
        "WSS_Content_CreatedByCode", // Content Database Name
        null, // Database Login Name
        null // Database Login Password
        )) {
            Console.WriteLine("Created Site Collection: {0}",
                newSiteCollection.Url);
    }
}

Creating a new site collection uses the method of the SPSiteCollection type, to which you can get a reference from the SPWebApplication.Sites property. The method has many different overloads; the code excerpt uses one of the most complete signatures, which is as follows:

public SPSite Add(
    string siteUrl,
    string title,
    string description,
    uint nLCID,
    uint compatibilityLevel,
    string webTemplate,
    string ownerLogin,
    string ownerName,
    string ownerEmail,
    string secondaryContactLogin,
    string secondaryContactName,
    string secondaryContactEmail,
    string databaseServer,
    string databaseName,
    string userName,
    string password
)

This example shows that you can define each and every detail of the site collection configuration, including the website template name to use, and you can even assign a dedicated content database. Table 5-9 lists some of the most common website template values.

Creating a new site collection assumes that the site collection (http://devbook.sp2013.local/) will allow you to create another site collection under the sites managed path of the parent web application. The sites managed path is available out of the box for any SharePoint web application. If you need to create a root site collection from scratch, however, you should retrieve a reference to the SPWebApplication instance through an SPFarm object.

After you have a site collection, at some point you will probably need to create one or more websites in it. Creating a new website contains a code excerpt that uses the SPWebCollection.Add method. The method also has many overloads. The following is the overload signature used in Creating a new website:

public SPWeb Add(
    string strWebUrl,
    string strTitle,
    string strDescription,
    uint nLCID,
    string strWebTemplate,
    bool useUniquePermissions,
    bool bConvertIfThere
)

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb newWeb = site.AllWebs.Add(
        "MyBlog", // Web Site Url
        "Blog Created By Code", // Web Site Title
        "Blogging Site Created By Code", // Web Site Description
        1033, // LCID
        "BLOG#0", // Web Site Template Name
        true,  // Use Unique Permissions
        false // Convert an existing folder
        )) {
            Console.WriteLine("New Web Site URL: {0}", newWeb.Url);
    }
}

While creating a website, you can specify a website template name or an object of type SPWebTemplate. This last type has a CompatibilityLevel property, which enables you to specify whether you are creating a SharePoint 2010 or SharePoint 2013 site. Some of the available values for this argument are illustrated in Table 5-10.

Note the Boolean useUniquePermissions argument that’s used in Creating a new website. This is useful for specifying whether to inherit permissions from the parent site collection or whether the new site should have unique permissions. The bConvertIfThere argument is also interesting; when true, it instructs SharePoint to convert an existing folder into the child website; when false, it causes SharePoint to throw an exception if a folder already exists with the URL requested for the new website.

Of course, to be able to create a new website inside an existing site collection at all, you need to access the Server Object Model with a user account that has sufficient permissions.

This section includes several examples related to managing lists and list items. For example, you will learn how to create lists, as well as how to create, update, and delete items within those lists.

Creating a new title

To create a new list of items, you can use Creating a new list of contacts in a website and configuring the list properties as a pattern. It demonstrates how to create a list of contacts and configure the list properties.

Creating a new list of contacts in a website and configuring the list properties

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb web = site.OpenWeb()) {
        Guid newListId = web.Lists.Add(
            "Contacts", // List Title
            "Company's Contacts", // List Description
            SPListTemplateType.Contacts // List Template Type
            );
        SPList newList = web.Lists[newListId];
        newList.OnQuickLaunch = true;
        newList.ReadSecurity = 1; // All users have Read access to all items
        newList.WriteSecurity = 2; // Users can modify only items they've created                
        newList.Update();
        Console.WriteLine("Created list: {0}", newList.Title);
    }
}

Creating a new list of contacts in a website and configuring the list properties exploits the SPListCollection.Add method, using one overload that specifies the list template using an enumeration value. Here’s the signature of the Add method used:

public virtual Guid Add(
    string title,
    string description,
    SPListTemplateType templateType
)

The SPListTemplateType enumeration defines about 60 templates that cover the most common list scenarios. If you wish to create a list using a custom template, you can browse the ListTemplates property of the current SPWeb instance, selecting the corresponding SPListTemplate instance and using the following overload of the SPListCollection.Add method instead:

public virtual Guid Add(
    string title,
    string description,
    SPListTemplate template
)

All the overloads of the SPListCollection.Add method return a Guid value that corresponds to the ID of the newly created list. To configure the list you just created, you need to retrieve a reference to it using that ID. Creating a new list of contacts in a website and configuring the list properties uses the SPList object to configure the list so that it will appear on the Quick Launch menu. It configures the default item-level permissions to let all users read every item but change only items that they created. You can see the result of this item-level permissions configuration made through code in Figure 5-3.

Remember, as soon as you have finished configuring any object from the Server Object Model, you must invoke the Update method to confirm the changes.

Figure 5-3. Item-level permissions resulting from the code in Creating a new list of contacts in a website and configuring the list properties.

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb web = site.OpenWeb()) {
        try {
            SPList list = web.Lists["Contacts"];
            try {
                SPListItem newItem = list.Items.Add();
                newItem["Last Name"] = "Pialorsi";
                newItem["First Name"] = "Paolo";
                newItem["E-mail Address"] = "[email protected]";
                newItem.Update();
            }
            catch (ArgumentException) {
                Console.WriteLine("Invalid Field Name!");
            }
        }
        catch (ArgumentException) {
            Console.WriteLine("Invalid List Title!");
        }
    }
}

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb web = site.OpenWeb()) {
        try {
            SPList list = web.Lists["Contacts"];
            SPListItem itemToChange = list.GetItemById(1);
            itemToChange["Last Name"] += " - Changed!";
            itemToChange.Update();
        }
        catch (ArgumentException) {
            Console.WriteLine("Invalid List Title or invalid List Item ID!");
        }
    }
}

SPListItem itemToChange = list.GetItemByIdSelectedFields(1, "Last Name");

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb web = site.OpenWeb()) {
        try {
            SPList list = web.Lists["Contacts"];
            SPListItem itemToChange = list.GetItemById(1);
            itemToChange["Last Name"] += " - Changed!";
            // Before Update, simulate a concurrent change           
            ChangeListItemConcurrently();
            itemToChange.Update();
        }
        catch (SPException ex) {
            Console.WriteLine(ex.Message);
        }
    }
}

Save Conflict. Your changes conflict with those made concurrently by another user. If you want your changes to be applied, click Back in your Web browser, refresh the page, and resubmit your changes.

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb web = site.OpenWeb()) {
        SPList list = web.Lists["Contacts"];
        SPListItem itemToDelete = list.GetItemById(1);
        itemToDelete.Delete();
    }
}

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb web = site.OpenWeb()) {
        SPList list = web.Lists["Contacts"];
        SPQuery query = new SPQuery();
        // Define columns to retrieve
        query.ViewFields = "<FieldRef Name="Title" />
           <FieldRef Name="FirstName" /><FieldRef Name="Email" />";
        // Force retrieving only the selected columns
        query.ViewFieldsOnly = true;
        // Define the query. Remember to remove the <Query></Query> container 
        // tag, in case of any
        query.Query = "<Where><Contains><FieldRef Name="Email" />
           <Value Type="Text">@devleap.com</Value></Contains></Where>";
        // Define the maximum number of results for each page (like a SELECT TOP)
        query.RowLimit = 10;
        // Query for items
        SPListItemCollection items = list.GetItems(query);
        foreach (SPListItem item in items) {
            Console.WriteLine("{0} {1} - {2}",
                item["First Name"],
                item["Last Name"],
                item["E-mail Address"]);
        }
    }
}

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb web = site.OpenWeb()) {
        SPList list = web.Lists["Contacts"];
        SPQuery query = new SPQuery();
        // Define columns to retrieve
        query.ViewFields = "<FieldRef Name="Title" />
           <FieldRef Name="FirstName" /><FieldRef Name="Email" />";
        // Force retrieving only the selected columns
        query.ViewFieldsOnly = true;
        // Define the query
        query.Query = "<Where><Contains><FieldRef Name="Email" />
           <Value Type="Text">@domain.com</Value></Contains></Where>";
        // Define the maximum number of results for each page (like a SELECT TOP)       
        query.RowLimit = 5;
        Int32 pageIndex = 1;
        Int32 itemIndex = 1;
        do {
            Console.WriteLine("Current Page: {0}", pageIndex);
            // Query for items
            SPListItemCollection items = list.GetItems(query);
            foreach (SPListItem item in items) {
                Console.WriteLine("{0} - {1} {2} - {3}",
                    itemIndex,
                    item["First Name"],
                    item["Last Name"],
                    item["E-mail Address"]);
                itemIndex++;
            }
            // Set current position to make SPQuery able
            // to set the start item of the next page
            query.ListItemCollectionPosition =
                items.ListItemCollectionPosition;
            pageIndex++;
        } while (query.ListItemCollectionPosition != null);
    }
}

Current Page: 1
1 - First Name 001 Last Name 001 - [email protected]
2 - First Name 002 Last Name 002 - [email protected]
3 - First Name 003 Last Name 003 - [email protected]
4 - First Name 004 Last Name 004 - [email protected]
5 - First Name 005 Last Name 005 - [email protected]
Current Page: 2
6 - First Name 006 Last Name 006 - [email protected]
7 - First Name 007 Last Name 007 - [email protected]
[etc. ]

Paged=TRUE&p_ID=8

Document libraries and files are critical for many real-world SharePoint solutions. In this section, you will learn how to create document libraries, and how to upload, download, update, and manage documents. Remember that in SharePoint 2013, a document library, from a web UI perspective, is shown as an app. However, it is still a document library as it was in previous editions of SharePoint.

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb web = site.OpenWeb()) {
        SPListTemplate listTemplate = web.ListTemplates["Document Library"];
        SPDocTemplate docTemplate =
            (from SPDocTemplate dt in web.DocTemplates
                where dt.Type == 122 
                // 122 means "A blank Microsoft Excel document"
                select dt).FirstOrDefault();
        Guid newListId = web.Lists.Add(
            "Invoices", // List Title
            "Excel Invoices", // List Description
            listTemplate, // List Template
            docTemplate // Document Template (i.e. Excel)
            );
        SPDocumentLibrary newLibrary = web.Lists[newListId] as SPDocumentLibrary;
        newLibrary.OnQuickLaunch = true;
        newLibrary.EnableVersioning = true;
        newLibrary.Update();
    }
}

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb web = site.OpenWeb()) {
        SPDocumentLibrary library = web.Lists["Invoices"] as SPDocumentLibrary;
        using (FileStream fs = new FileStream(@"....DemoInvoice.xlsx",
            FileMode.Open, FileAccess.Read, FileShare.Read)) {
            SPFile fileUploaded = library.RootFolder.Files.Add(
                "DemoInvoice.xlsx", fs, true);
            Console.WriteLine("Uploaded file: {0}", fileUploaded.Url);
        }
    }
}

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb web = site.OpenWeb()) {
        SPDocumentLibrary library = web.Lists["Invoices"] as SPDocumentLibrary;
        SPFile fileToDownload = web.GetFile(library.RootFolder.Url +
            "/DemoInvoice.xlsx");
        Int32 bufferLength = 4096;
        Int32 readLength = bufferLength;
        Byte[] buffer = new Byte[bufferLength];
        Stream inStream = fileToDownload.OpenBinaryStream();
        using (FileStream outStream = new FileStream(
            @"....DemoInvoiceDownload.xlsx",
            FileMode.OpenOrCreate, FileAccess.Write, FileShare.None)) {
            while (readLength == buffer.Length) {
                readLength = inStream.Read(buffer, 0, bufferLength);
                outStream.Write(buffer, 0, readLength);
                if (readLength < bufferLength) break;
            }
        }
    }
}

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb web = site.OpenWeb()) {
        SPDocumentLibrary library = web.Lists["Invoices"] as SPDocumentLibrary; 
        SPFile file = web.GetFile(library.RootFolder.Url + "/DemoInvoice.xlsx");
        if (file.CheckOutType == SPFile.SPCheckOutType.None) {
            // If the file is not already checked out … check it out
            file.CheckOut();
        }
        else {
            // Otherwise check it in leaving a comment
            file.CheckIn("File Checked-In for demo purposes",
                SPCheckinType.MajorCheckIn);
        }
    }
}

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb web = site.OpenWeb()) {
        SPDocumentLibrary sourceLibrary =
           web.Lists["Invoices"] as SPDocumentLibrary;
        SPDocumentLibrary destinationLibrary =
           web.Lists["Invoices History"] as SPDocumentLibrary;
        SPFile file = web.GetFile(sourceLibrary.RootFolder.Url +
           "/DemoInvoice.xlsx");
        if (move) {
            // It is a file moving action
            file.MoveTo(destinationLibrary.RootFolder.Url +
                "/DemoInvoice_Moved.xlsx", true);
        }
        else {
            // It is a file copy action
            file.CopyTo(destinationLibrary.RootFolder.Url +
               "/DemoInvoice_Copied.xlsx", true);
        }
    }
}

using (SPSite site = new SPSite(
"http://devbook.sp2013.local/sites/CreatedByCode/")) {
    using (SPWeb web = site.OpenWeb()) {
        SPDocumentLibrary library = web.Lists["Invoices"] as SPDocumentLibrary;
        SPFile file = web.GetFile(library.RootFolder.Url + "/DemoInvoice.xlsx");
        Console.WriteLine("Available versions:");
        foreach (SPFileVersion v in file.Versions) {
            Console.WriteLine("Version: {0} - URL: {1}", v.VersionLabel, v.Url);
        }
        SPFile fileOfSecondLastVersion =
            file.Versions[file.Versions.Count - 1].File;
        Console.WriteLine(fileOfSecondLastVersion.Name);
    }
}

The tasks discussed in this section involve the management of users and groups. You will learn how to create and manage a user, how to control users’ membership against groups, and how to define custom permission levels to assign specific permissions to users or groups.

using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
    using (SPWeb web = site.OpenWeb()) {
        web.Groups[0].Users.Add("SP2013\TestUser", "[email protected]",
           "Test User", null);
    }
}

using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
    using (SPWeb web = site.OpenWeb()) {
        SPUser userAdded = web.EnsureUser("SP2013\AnotherTestUser");
        Console.WriteLine(userAdded.Xml);
    }
}

using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
    using (SPWeb web = site.OpenWeb()) {
        SPUser user = web.EnsureUser("SP2013\AnotherTestUser");
        web.Groups[web.Title + " Members"].AddUser(user);
    }
}

using (SPSite site = new SPSite("http://devbook.sp2013.local/")) {
    using (SPWeb web = site.OpenWeb()) {
        SPUser user = web.EnsureUser("SP2013\AnotherTestUser");
        SPRoleDefinition newRoleDefinition = new SPRoleDefinition();
        newRoleDefinition.Name = "Custom Permission Level";
        newRoleDefinition.Description = "View Pages, Browse Directories, " +
           "Update Personal Web Parts";
        newRoleDefinition.BasePermissions = SPBasePermissions.ViewPages |
           SPBasePermissions.BrowseDirectories |
           SPBasePermissions.UpdatePersonalWebParts;
        web.RoleDefinitions.Add(newRoleDefinition);
        SPPrincipal principal = user;
        SPRoleAssignment newRoleAssignment = new SPRoleAssignment(principal);
        newRoleAssignment.RoleDefinitionBindings.Add(
           web.RoleDefinitions["Custom Permission Level"]);
        web.RoleAssignments.Add(newRoleAssignment);
    }
}