Web collaboration consultant, public speaker and Microsoft Press Author. @resing on twitter

Do you have SharePoint PowerShell to SharePoint API translations in your tool belt?

An Old SharePoint API Confusion

If you hadn’t seen it before and someone told you there was .Net SharePoint Framework object called SPSite what would you think it was for? It’s commonly used object in SharePoint C# code, and you might think it would represent a SharePoint Site. But it’s not quite that. An SPSite is really a collection of sites. In end user and administration documentation, a collection of sites is commonly referred to as a Site Collection. It’s the SPWeb object that represents what is more commonly called a SharePoint Site.

Code, including the SharePoint API, can be unfriendly to changes like renaming SPSite to SPSiteCollection and SPWeb to SPSite. It would break existing code using the old names. So even though the SPSite and SPWeb names don’t match common use now, we’re kind of stuck with it.

A New PowerShell to SharePoint API Translation Issue

This kind of name confusion used to only be a problem for developers new to SharePoint. With the introduction of PowerShell as an administration tool, now it can be a source of confusion for SharePoint Administrators. Even experienced SharePoint Administrators might not have a need to look in the SharePoint API before. Every PowerShell object is a .Net object in the end. Since PowerShell is a tool aimed at Administration tasks, administrators will now get some more benefit from the MSDN side of Microsoft.com, because TechNet doesn’t have the information needed in the example below.

Get-SPTimer job (PowerShell) retrieves an SPJobDefinition (SharePoint API)

An example I came across today while troubleshooting a User Profile Synch issue was the SPJobDefintion to SPTimerJob confusion. Take a look at the first 5 lines of help for the SharePoint PowerShell Command Get-SPTimerJob:

PS C:UsersAdministrator> get-help get-sptimerjob

NAME
    Get-SPTimerJob
   
SYNOPSIS
    Returns timer jobs.

What a revelation! Get-SPTimerJob returns timer jobs. The help goes on to include syntax, a brief description and a helpful link to the table of contents of the SharePoint PowerShell Reference on TechNet.

In the following example of output for Get-SPTimerJob, you can see that you might want some more information.

Name                 Schedule             Last Run           
—-                 ——–             ——–           
job-workflow-fail… every 15 minutes … 3/2/2011 3:15:14 PM
ExpirationProcessing weekly at sat 23:… 2/14/2011 8:18:41 AM

But where can you find more about the results of this operation? Would your first guess be the SPJobDefinition Members reference of MSDN? Not me. After a lot of research, I found a powershell command to tell me the properties I could use to expand the information returned.

get-sptimerjob | sort-object name | where {$_.Name -match "profile"} | get-member -membertype property | out-file c:installget-sptimerjobGetMemberoutput.txt

Note: Sorting and filtering as demonstrated above are a must for Get-SPTimerJob because the default output is every timer job. And there are a lot of timer jobs. You also might want to output the results to a text file, like after the last pipe above, because it’s easier to search through the results in Notepad than in the console window.

After some searching through the SharePoint SDK, I found the SPJobDefinition Properties closely matched the output of the command above. The property I was looking for is called IsDisabled. (My first guess was enabled.) Now that I know the name of the property, I can add IsDisabled to a Select-Object statement piped from Get-SPTimer to add that to the list of fields displayed. But it took a lot of PowerShell learning and some translation from Get-Member to the SharePoint API to find the meaning of the properties I could choose from.

Here’s the final command I used. I found out one job with profile in it’s name is disabled on my test farm:

get-sptimerjob | Select Name, IsDisabled | Where {$_.Name -match "profile"}

What to do? Build a glossary?

If you have other SharePoint PowerShell to SharePoint API translations you use, feel free to share them in the comments below. If we get enough, maybe we can build a glossary and post it on NothingButSharePoint.

Leave a Reply