SharePoint Troubleshooting Tools – PowerShell

Home » SharePoint Tips & Tricks » SharePoint Troubleshooting Tools – PowerShell

So far in this series we have covered a few of the tools a SharePoint administrator must master in IIS Logs, ULS Logs, and ULSViewer.  Another that tool that every SharePoint administrator absolutely has to master is PowerShell.  Every Microsoft application platform these days has a PowerShell API, including the cloud applications. To truly set yourself apart as an automation-focused administrator you need to learn PowerShell.  In this article we will cover the basics of SharePoint PowerShell. We’ll also touch on some ideas on how you can put it to work for you.

Getting Started: Permissions

First things first.  In order to run PowerShell commands against SharePoint (object model and databases) you are going to need the permissions to do so.  You are going to need to be a farm administrator and have your account added to the SP Shell Admin group on the databases.  Actually your account can be granted object model and limited content database access if you do not need full farm access.  This is done using the “-Database” parameter of the Add-SPShellAdmin cmdlet.  For our purposes we are going to ensure your account has full access to everything.

There are a couple different PowerShell IDE’s that are available as part of Windows Server and the SharePoint installation where you can author and run PowerShell scripts.  These are PowerShell ISE (integrated scripting environment) and the SharePoint Management Shell.  You can find these by searching form the Windows Server start menu.  ISE is better suited for writing longer reusable scripts where the SP Management Shell is good for quick commands.  Another very good options is Visual Studio Code which is more powerful than ISE, but we won’t cover that here.  It requires a separate install and is free from Microsoft’s website.

SharePoint 2016 Management Shell

Windows PowerShell ISE

The SharePoint Management Shell is just a PowerShell console window with the SharePoint module pre-loaded for you.  The SharePoint Module is the SharePoint PowerShell API that contains hundreds of cmdlets specifically for SharePoint.   If you prefer ISE then you’ll need to add “Add-PSSnapin Microsoft.SharePoint.Powershell” as the first line of your file to gain access to the SharePoint cmdlets.

Adding User Accounts

If you open the SharePoint Management shell and you see an error that the local farm is not accessible, then your account has not yet been added using the Add-SPShellAdmin cmdlet.

PowerShell - the local farm is not accessible

To add this user account to the SP Shell Access role you’ll need to run:

PS C:\Users\andy> Add-SPShellAdmin -UserName DEMO1604\brett

Note the account you’re using to run this command will need to have DB_Owner on the target database.  In this case the SharePoint configuration database.   This also adds the user account to the WSS_Admin_WPG local groups on each farm SharePoint server.

Checking Brett’s SQL permissions we see that he was added as a login in SQL Server. He was also added to the SP Shell Access and SPDataReader roles on the configuration database.

Checking SQL permissions

Granting Access

We have not added Brett’s access to our content databases yet, so he will not be able to run PowerShell commands against sites in those content databases.  We only have one content DB in our farm named WSS_Content_usclouddemo1604.uscloud.com.  Running specific commands against the site content will result in access denied errors to the content database.

Failed login - access denied

To grant Brett access we’ll need to run the same Add-SPShellAdmin command but specify the database name as a parameter.  We have to use the Get-SPContentDatabase cmdlet inside of parentheses because the –Database parameter requires a specific SPContentDatabase object type to be passed into it.

Shell admin access granted

Now Brett has been granted Shell Admin Access on the configuration database and our content database.  He can now run PowerShell commands that interact with those databases behind the scenes.  If Brett is going to need to run PowerShell against specific service applications like search or user profile, he will need additional Administrative rights to those service applications and their databases.

There is a wealth of information from here online about the available SharePoint PowerShell commands.   Check out this API reference. The above should get you the basic access you need to get started playing with SharePoint using PowerShell.

If you have any other questions, contact us for some answers.

2018-06-21T11:01:44+00:00 June 21st, 2018|

Leave A Comment