Editor's note: Contributor Craig Pilkenton is a Senior Microsoft Consultant for CDW.com.
Powershell is the tool for getting things done in all versions of SharePoint (and your servers/desktops too!). It has the capability to automate, monitor, notify, and even 'react' to results. Not only does it have custom compiled 'activities' to get work done, it has the ability to call any command-line executable or pull in .NET library's to handle anything not already given to us by Microsoft (or even our own cmdlets). In this article we'll go over how to use some of the new "manage content" SharePoint cmdlets to interact with the platform just as a user would.
SharePoint 2010 has over 600 built-in cmdlets (pronounced as command-lets) to build, manage, and update the platform (see the TechNet reference). If you've ever opened a DOS command prompt, typing “dir” or “cd” to get a list of files, then you are ready to use Powershell. If not, Ravikanth C.'s article 'NothingButSharePoint.com: Getting started with PowerShell for SharePoint 2010 Administrators' is a great primer for this.
Now we move onto the setup of building a reusable, parameterized script file (.ps1) to do our work. While we have the ability to build our own cmdlets using Visual Studio 2010, using .ps1 files allows us to modify the code as often as need with it only being compiled at runtime by Powershell. Once the logic and functionality is rock-solid you could then convert it into your own Verb-Noun cmdlet.
There are a couple of considerations as you get started:
- Security: the account that will be running as for the Powershell script needs to have at least Contributor rights on the SharePoint site you are targeting, as well as read on the file location. If you plan on using this as a Scheduled Task, you may want to run as the Farm Administrator account so there are no permission issues.
- Toolset: while you can just use Notepad on your computer/server to put this together, there are many free tools out there that will give you IntelliSense, color-coding, debugging, and even version control if needed. My favorites are PowerGUI, PowerSE, NotePad++, and of course the Windows ISE (Server 2008 & Windows 7).
Let's get to work. Here's the file we'll be working from in this example:
I've marked up the file to denote what each section does but I'll call out the important areas below by line number.
- Line 1: this is an example for calling the file with parameters and their format. When saving, name the file in a format that makes sense to you.
- Lines 2-7: receive passed-in parameters make this script reusable so it can be called by other master scripts and/or be called as a Scheduled Task--
- SharePoint site URL
- The Document Library on the above site to target for injection (can also target a Folder/SubFolder in the Library)
- The file name and its network location (e.g. ""\\server\some_directory\", etc.)
- Lines 20-22: this section uses the new Get-SPWeb cmdlet and its methods for injection--
- Store a reference to the site in the $spWeb variable
- Store a reference to a Document Library in the site in the $spFolder variable
- Store a reference to the FileCollection object inside the Document Library in the $spFileCollection object
- Lines 25-26: here we store a reference to the file in the $file variable for use later and checks it length to verify it exists
- Lines 29-30: in this portion using the FileCollection variable created above, we get a reference to the file in the Library (if it exists) and force a Check-Out--
- Note: if it doesn't already exist an error will show on the .CheckOut() command but the script will continue on
- Line 33: now to inject the file we call the add file method for the FileCollection variable giving it the file name to add as (we could make it something else) and the file variable using its .OpenRead() method
- Lines 36-39: in this final section we finish up the processing--
- Rebuild the FileCollection variable (otherwise our new file won't show if it didn't exist before)
- Obtain a reference to the file in the Library again
- Fire the the Check-In command for that file
- Dispose of the reference to the Site from the Get-SPWeb cmdlet (Note: this is very important to avoid memory issues with unclosed SharePoint references
Now that we have the basics put together, to get it to do the work we need open a Powershell command prompt & navigate to the directory where your scripts will live (e.g. "CD E:\Powershell\" + Enter, etc.).
Once there we type the name of the script we saved and add in the parameters setup initially to start running the script:
.\SharePoint_FileCollection_Submit.ps1 "http://mySPS.com/Department/" "Reports" "\\A01\SharePoint\files" "Something.PDF"
The Write-Host sections I added will tell us the progress of our script, including any errors that may occur.
And that's all we need to post files to SharePoint. We could also enhance the file's capabilities such as setting Metadata values on that document, adding Check-In comments, enumerating through multiple files in a directory instead of just one, or even firing other Powershell scripts letting user's know the work was completed. If you'd like to utilize a copy of the code for yourself, here is a link to my SkyDrive location, the file is called UploadDocsToSharePoint.ps1.