Update 10/25/2017: This article originally appeared on ITUnity.com but as that site has been decommissioned I’ve republished it here.

As a developer working with earlier versions of SharePoint, specifically SharePoint 2007 and earlier, your options for working with SharePoint from off-server client applications was pretty limited. You had some SOAP-based web services that you could call, which are still available today, but you were somewhat limited with what you could do with those services, and using them could be somewhat cumbersome. With SharePoint 2010, Microsoft introduced new Client-Side Object Models (CSOM) for working with SharePoint remotely: for .NET client applications on or off the server you had the .NET CSOM API, and from within the browser you could use the ECMAScript API, also known as JSOM, and for working within Silverlight applications there is a Silverlight-specific version of the .NET CSOM API. These new APIs, which are essentially a subset of what you can do with the server-side API, made it considerably easier and faster to develop client-side, or remote applications that consumed data from SharePoint (or otherwise manipulated SharePoint in some fashion).

When you’re working with PowerShell you’re basically working within a .NET environment so the API you’ll be most interested in is the .NET CSOM API (which I’ll simply refer to as CSOM going forward) as this is going to allow you to work with an individual Site Collection, and the various elements within it, all in a type-safe manner. What this means is that when you’re working with a SharePoint list or content type or a field or whatever, you want to have a .NET object that accurately reflects the asset you’re working with and provides you with methods and properties that make it clear what information you can view and change and what operations you can perform against the object. CSOM gives you all of this as well as the ability to perform operations in batch so that we can reduce some of the chatter between the client and the server. What this all boils down to is that there’s very little guess work about what you can and cannot do, thereby making it pretty easy to manipulate the data and structure of your Site Collections, all without deploying any code to the SharePoint server. And that last point is a critical one because when you’re working with Office 365, you can’t deploy code to the server so the ability to operate remotely in a type-safe manner is vital.

Getting started

There’s a fair bit of discussion that we could get into regarding how CSOM works internally but what you should be really concerned about here is how to use the API to connect to your Site Collection and then how to start using the various objects available to you. Before you can do that though, you have to load up the .NET assemblies that contain the objects you need. There are a few ways that you can get the assemblies and get them loaded into memory for use. Let’s first look at what assemblies you need and then I’ll cover where you can get them.

To perform the most common operations against a Site Collection there are two assemblies you must load:

  • Microsoft.SharePoint.Client.dll
  • Microsoft.SharePoint.Client.Runtime.dll

These will suffice for most things you’ll need to do but if you want to work with items such as publishing features and taxonomy and search, to name just a few, you’ll need to load one or more of these additional assemblies:

  • Microsoft.SharePoint.Client.DocumentManagement.dll
  • Microsoft.SharePoint.Client.Publishing.dll
  • Microsoft.SharePoint.Client.Search.dll
  • Microsoft.SharePoint.Client.Search.Applications.dll
  • Microsoft.SharePoint.Client.Taxonomy.dll
  • Microsoft.SharePoint.Client.UserProfiles.dll
  • Microsoft.SharePoint.Client.WorkflowServices.dll

So where do you get these assemblies from? If you’ve got the SharePoint Online Management Shell installed then you already have the first two assemblies – they’ve been loaded for you in the global assembly cache, or GAC (C:\Windows\Microsoft.NET\assembly\GAC_MSIL) and you can also find them in the Program Files folder (C:\Program Files\SharePoint Online Management Shell\Microsoft.Online.SharePoint.PowerShell). If you don’t have the SharePoint Online Management Shell installed, though you should, then you can get the assemblies from either an on-premises installation of SharePoint 2013 by looking in _C:\Program Files\Common Files\microsoft shared\Web Server Extensions\15\ISAPI_, or you can download the SharePoint 2013 Client Components redistributable package from http://www.microsoft.com/en-us/download/details.aspx?id=35585. Note that the redistributable package installs the assemblies into the GAC and in a SharePoint Root’s ISAPI folder on your machine: C:\Program Files\Common Files\microsoft shared\Web Server Extensions\16\ISAPI.

Unfortunately, the SharePoint Online Management Shell only installs the first two assemblies so if you need the additional assemblies (publishing, search, etc.) and all you have is the SharePoint Online Management Shell then you’ll need to either grab those additional assemblies from an on-premises installation or install the redistributable package.

The mechanism you use to load the assemblies into memory depends on whether the assembly was installed in the GAC or not. If it was installed in the GAC (as will be the case if you installed the SharePoint Online Management Shell and/or the redistributable package) then you can use the commands (shown in yellow) in figure 1:

Figure 1: You can load the .NET assemblies without the extension using the LoadWithPartialName method if the assembly was installed in the GAC.

As figure 1 shows, simply provide the name of the assembly, without the extension, to the LoadWithPartialName static method of the System.Reflection.Assembly class. If you copied the files from an on-premises installation and are loading the file from a specific location then you would load the assembly by passing the full path of the file to the LoadFile static method of the same class, as shown in figure 2:

Figure 2: If you copied files from an on-premises installation, you must use the LoadFile method to pass the full path of the file of the assembly.

All that said, if you’re in the SharePoint Online Management Shell or have otherwise loaded the module using the Import-Module cmdlet (Import-Module Microsoft.Online.SharePoint.PowerShell) then these two core assemblies will already be loaded for you and you only need to worry about loading the additional assemblies when needed.

Getting connected

Now that you’ve got the required assemblies loaded into memory, you are now ready to establish a connection to a Site Collection within your tenancy. To do this you’re going to use two objects:

The SharePointOnlineCredentials object simply stores the credentials you need in order to connect to your environment. Just pass in your username and password to the object constructor and then use this object to initialize the ClientContext object, along with the URL of the Site Collection you’re connecting to. When creating the SharePointOnlineCredentials object, I strongly recommend you do not hard-code your username and password either within your script or by typing in clear text within your console window; instead you should use the Get-Credential cmdlet to retrieve your credentials and then use the properties on that object to initialize the SharePointOnlineCredentials object, as shown in figure 3:

Figure 3: Best practice: use the Get-Credential cmdlet to retrieve your credentials and then use the properties on that object to initialize the SharePointOnlineCredentials object.

Once you’ve created your credential object you can now create the ClientContext object and set the credentials, as shown in figure 4:

Figure 4: Create the ClientContext object and set the credentials.

And that’s it – you’re now connected to your environment and ready to start doing some damage. 😉

Because connecting to a Site Collection would be a pretty common task, I’ve gone ahead and turned this into a simple function that you can utilize to connect to your Site Collection:

Simply call the Connect-SPOSite function and pass in the URL of the Site Collection you wish to connect to (make sure you set the output to a variable that you can use later). If you have not previously provided credentials then it will prompt you for them, otherwise it will use the credentials that it has stored for you in the global scope (the function assumes you have the SharePoint Online Management Shell installed). Throughout the remainder of this article you’ll use this function to connect to your Site Collection. To load the function into memory for use simply save it to a file, in this case I called it Connect-SPOSite.ps1, and then execute the file from your console or script. Figure 5 shows how to load the function into memory and then execute it, passing in the Site Collection to connect to:

Figure 5: Load the Connect-SPOSite function into memory and execute it by passing in the URL of the Site Collection you want to connect to.

In this example it’s the first time I’ve attempted to execute a script from this particular machine so I had to run the Set-ExecutionPolicy cmdlet where I chose to use the least restrictive option, Bypass, so that I can run any scripts I want to run (if you have user account control enabled make sure that you load the console as Administrator otherwise the Set-ExecutionPolicy cmdlet will fail). You won’t need to run the Set-ExecutionPolicy cmdlet again but I wanted to make sure I showed it here otherwise your script won’t load. Finally, the Connect-SPOSite function is going to return the ClientContext object so, as I previously noted, make sure you set the output of the function to a variable as you’ll need to use this later.

Summary

In this article I introduced you to how to load the CSOM assemblies into memory and then I introduced a simple helper function that you can utilize to quickly get connected to a SharePoint Online Site Collection. In the next article, Using the SharePoint CSOM API with SharePoint Online and Windows PowerShell, I will demonstrate how you can work with the SharePoint CSOM API to load and execute queries against your Site Collection.