The SharePoint that Nobody Sees

When most people think about programming for SharePoint, the first thing that comes to mind is Web Parts. Web parts are the primary user-interface component in SharePoint. They make laying out sites very easy; however, SharePoint Web Parts are notorious for having one of the steepest "Hello World" learning curves in the software industry. Fortunately, others have covered the art of writing (and installing) web parts far better than I can, so I'm not going to talk about them.

Today I'm going to talk a bit about the SharePoint API, and writing your own command-line utilities. I normally leave the hard-core programming tasks (like those web parts) to others, and stick to system architecture, administration, and usage issues; however, many an admin has needed to break out a copy of BASIC to throw together a quick and dirty utility. I'm no exception! :) This article will demonstrate how to crawl the SharePoint site hierarchy, and help get you started writing your own tools. (Note: the API itself is the same one you use for web parts and other "visual" aspects of SharePoint, so this will be helpful for more "mainstream" applications, too!)

What You Need

Creating a utility for SharePoint is very easy. You only need a few things:

1. A SharePoint Server
2. Visual Studio
3. Administrative rights on the server.

Almost as important are some things you don't need:

1. Knowledge of asp.net config files
2. Strong naming
3. Code signing.
4. Any knowledge of asp.net, html, or web services.

Setting up the Project

Start by creating a new solution in Visual Studio. First, pick your language (I'm using VB). Then you'll need to scroll down to a project type is rarely used in this day of Windows, web services, and asp.net - the "Console Application."

Since this is a SharePoint utility, the first thing you will need to do is add a reference to the SharePoint.dll. It normally won't be in the default .net tab, so you will need to browse for it. If you're developing on your web server, you will usually find it at c:\program files\common files\microsoft shared\web server extensions\60\isapi:

If you are not developing on a SharePoint server, you can copy this dll to your development system and add the reference from there. While you won't be able to run your program except on an actual SharePoint server, having the dll locally will allow you use Intellisense code completion in Visual Studio.

Finally, you will need to tell your module that you will be using the SharePoint functionality. At the top of the file (above the module tag), add the following lines:

Imports Microsoft.SharePoint  
Imports Microsoft.SharePoint.Administration  
Imports System.Security.Principal

Because you need to access the SharePoint API in the context of a user, the System.Security.Principal module gives you access to the Windows Impersonation Context.

Know the Code

The SharePoint objects we will use in this demo are:

1. SPGlobalAdmin, to give us access to all of the virtual servers on the system. If the virtual server is extended for SharePoint, that is a "SPVirtualServer".
2. SPVirtualServer, gives access to the properties of a specified virtual server. This contains one or more "SPSite" objects.
3. SPSite, which is actually a Site Collection, also known as a "top level site". It contains one or more "SPWeb" objects.
4. SPWeb, which is an individual SharePoint site or workspace.

In addition to declaring variables for each of these objects, we will declare one called "comline" to hold any command line parameters you may pass to your utility.

Here is the skeleton of the program, the contents of "sub main()"

  
Dim wic As WindowsImpersonationContext 
wic = WindowsIdentity.GetCurrent().Impersonate() 
Dim globalAdmin As New SPGlobalAdmin 
Dim q As Integer 
Dim virtServer As SPVirtualServer 
Dim siteCollection As SPSite 
Dim site As SPWeb 
Dim comline As String 
comline = Command() 
For Each virtServer In globalAdmin.VirtualServers 
 Try 
  For Each siteCollection In virtServer.Sites 
   For Each site In siteCollection.AllWebs 
    'do something here 
   Next 
  Next 
 Catch ex As Exception 
  Console.WriteLine(ex.Message) 
 End Try 
Next 
wic.Undo() 

The bulk of this is the variable declarations, and three nested "For Each" loops, one for each of the three collection objects. As it stands, this doesn’t do very much, but notice the lonely little comment inside the innermost loop - "'do something here". That is where you insert whatever you want your utility to do.

For example, let's say you want to know what themes are in use on your server. Add this line under the comment:

Console.WriteLine(site.Title & ", " & site.Url & ", " & site.Theme)

Then just build your solution. It will create an .exe file with the name you originally gave the project. That's your utility, and the only file you need to have on the SharePoint server. Just go to a command prompt, navigate to the folder holding the .exe, or copy it and type in the name. You will be presented with a nice list of all of the themes in use in your SharePoint environment. The simple change of adding a line like:

site.ApplyTheme("Corporate")

could make the utility set the theme on every site to a corporate standard.

This is just the beginning. Using this shell, you can run all sorts of reports, enforce standards, update choice fields in lists, or anything else you can imagine.