Manipulating SQL Agent Jobs through PowerShell

In our last post titled Loading and using SQL Server Management Objects in PowerShell, we demonstrated how to load and consume SQL Server Management Objects in PowerShell, which then allows us to access your SQL instance through an SMO instance object. Please make sure you read that post before continuing.

In this specific post, we will demonstrate and walk through how to use PSH and SMO to view and change SQL Agent jobs.

If you recall we had previously instantiated an object to our SQL Server instance and assigned it to our $sqlinstance variable as follows:

$sqlinstance = New-Object -TypeName Microsoft.SQLServer.Management.Smo.Server("server2\sql2016")

We can access the SQL Server Agent through its Jobserver property (returning an object of type Microsoft.SqlServer.Management.Smo.Agent.JobServer). This object has lots of available properties and methods available, but the one we are interested in is clearly the Jobs property (providing a collection of type Microsoft.SqlServer.Management.Smo.Agent.JobCollection). Obviously, this means we have to iterate over each one or access a specific element through the collections indexer.

For now, let’s take a look at all the jobs in the Jobs collection:

$sqlinstance.jobserver.jobs|Select-Object -Property Name, Description

This results in the following…

Name                    Description
----                    -----------
My Maintenance Job      No description available.
syspolicy_purge_history No description available.

Through the indexer we can access our job in question using its collection numerator:

$sqljob=$sqlinstance.jobserver.jobs[0]

Or via its named property:

$sqljob=$sqlinstance.jobserver.jobs['My Maintenance Job']

Either way, we now have an object which we can retrieve or change properties on.

The only guaranteed way to ensure your SQL job information is accurate appears to be calling the Refresh method on a specific job itself as follows:

$sqljob.Refresh()

Querying our specific job now shows that we now have a description value (albeit misspelled!).

$sqljob|Select-Object -Property Name, Description

Gives us…

Name               Description
----               -----------
My Maintenance Job My descriptionz2

Let’s fix that problem and change the description. Obviously, this should be a simple operation by setting the SQL job Description property:

$sqljob.Description = 'My description'

Unfortunately, if we take a look at the SQL job through SSMS (feel free to right-click and refresh the Agent node first), we see that our change has not taken effect.

In order to write back your change/s to the SQL Server instance you must call the objects Alter method as follows:

$sqljob.Alter()

And this is enough to update the SQL Job on the SQL instance!

This concludes what I hope was a fairly easy two-post demonstration of how to use SQL Server Management Objects and PowerShell and use them to programmatically manipulate your SQL Server instances. In this specific case we ultimately used SMO through PSH to query and manipulate a simple property on a SQL Job (the job description), however I hope you can visualize the potential for doing much more advanced operations using this method to the SQL job server and the entire SQL instance!