Share via

Get-SqlAgentJob

Module:
SqlServer Module

Gets a SQL Agent Job object for each job that is present in the target instance of SQL Agent.

Syntax

ByPath (Default) 

Get-SqlAgentJob
    [[-Name] <String>]
    [[-Path] <String>]
    [-AccessToken <PSObject>]
    [-TrustServerCertificate]
    [-HostNameInCertificate <String>]
    [-Encrypt <String>]
    [<CommonParameters>]

ByName 

Get-SqlAgentJob
    [[-ServerInstance] <String[]>]
    [[-Name] <String>]
    [-Credential <PSCredential>]
    [-ConnectionTimeout <Int32>]
    [-AccessToken <PSObject>]
    [-TrustServerCertificate]
    [-HostNameInCertificate <String>]
    [-Encrypt <String>]
    [<CommonParameters>]

ByObject 

Get-SqlAgentJob
    [[-Name] <String>]
    [-InputObject] <JobServer>
    [-AccessToken <PSObject>]
    [-TrustServerCertificate]
    [-HostNameInCertificate <String>]
    [-Encrypt <String>]
    [<CommonParameters>]

Description

The Get-SqlAgentJob cmdlet gets a SQL Agent Job object for each job that is present in the target instance of SQL Agent. If the name of the job is provided, the cmdlet gets only this specific job object.

This cmdlet supports the following modes of operation to get a collection of Job objects:

  • Specify the path of the SQL Agent instance.
  • Pass the instance of the SQL Agent in the input.
  • Invoke the cmdlet in a valid context.

Examples

Example 1: Get all Job instances from the specified server instance

PS C:\> Get-SqlAgent -ServerInstance MyServerInstance | Get-SqlAgentJob
Name                      Owner                Category                  Enabled    CurrentRunStatus     DateCreated               LastModified              JobID
----                      -----                --------                  -------    ----------------     -----------               ------------              -----
MyJob1                    Owner                [Uncategorized (Local)]   True       Idle                 6/2/2016 10:21:44 AM      6/2/2016 10:21:44 AM      841255df-06e8-43ef-b798-3...
MyJob2                    Owner                [Uncategorized (Local)]   True       Idle                 5/31/2016 2:40:58 PM      6/1/2016 5:09:40 PM       995b296a-cd35-4505-868a-3...
MyJob3                    Owner                [Uncategorized (Local)]   True       Idle                 5/25/2016 12:13:56 PM     5/25/2016 12:13:56 PM     01d2e61a-9a90-4f77-98f4-e...

This command gets all Job instances in the server instance named 'MyServerInstance'.

Example 2: Get a job instance by name from the specified server instance

PS C:\> Get-SqlAgent -ServerInstance MyServerInstance | Get-SqlAgentJob -Name MyJob1
Name                      Owner                Category                  Enabled    CurrentRunStatus     DateCreated               LastModified              JobID
----                      -----                --------                  -------    ----------------     -----------               ------------              -----
MyJob1                    Owner                [Uncategorized (Local)]   True       Idle                 6/2/2016 10:21:44 AM      6/2/2016 10:21:44 AM      841255df-06e8-43ef-b798-3...

This command gets the Job instance named 'MyJob1' in the Server Instance named 'MyServerInstance'.

Parameters

-AccessToken

The access token used to authenticate to SQL Server, as an alternative to user/password or Windows Authentication.

This can be used, for example, to connect to SQL Azure DB and SQL Azure Managed Instance using a Service Principal or a Managed Identity.

The parameter to use can be either a string representing the token or a PSAccessToken object as returned by running Get-AzAccessToken -ResourceUrl https://database.windows.net.

This parameter is new in v22 of the module.

Parameter properties

Type:PSObject
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ConnectionTimeout

Specifies the number of seconds to wait for a server connection before a time-out failure. The time-out value must be an integer Value between 0 and 65534. If 0 is specified, connection attempts do not time out.

Parameter properties

Type:Int32
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

ByName
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Credential

Specifies a PSCredential object used to specify the credentials for a SQL Server login that has permission to perform this operation.

Parameter properties

Type:PSCredential
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

ByName
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Encrypt

The encryption type to use when connecting to SQL Server.

This value maps to the Encrypt property SqlConnectionEncryptOption on the SqlConnection object of the Microsoft.Data.SqlClient driver.

In v22 of the module, the default is Optional (for compatibility with v21). In v23+ of the module, the default value will be 'Mandatory', which may create a breaking change for existing scripts.

This parameter is new in v22 of the module.

Parameter properties

Type:String
Default value:None
Accepted values:Mandatory, Optional, Strict
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-HostNameInCertificate

The host name to be used in validating the SQL Server TLS/SSL certificate. You must pass this parameter if your SQL Server instance is enabled for Force Encryption and you want to connect to an instance using hostname/shortname. If this parameter is omitted then passing the Fully Qualified Domain Name (FQDN) to -ServerInstance is necessary to connect to a SQL Server instance enabled for Force Encryption.

This parameter is new in v22 of the module.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-InputObject

Specifies a SQL Management Objects (SMO) object representing the SQL Server Agent being targeted.

Parameter properties

Type:JobServer
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

ByObject
Position:2
Mandatory:True
Value from pipeline:True
Value from pipeline by property name:False
Value from remaining arguments:False

-Name

Specifies the name of the Job object that this cmdlet gets. The name may or may not be case-sensitive, depending on the collation of the SQL Server where the SQL Agent is running.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:1
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Path

Specifies the path to the Agent of SQL Server on which this cmdlet runs the operation. If you do not specify a value for this parameter, the cmdlet uses the current working location.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

ByPath
Position:2
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ServerInstance

Specifies, as a string array, the name of an instance of SQL Serverwhere the SQL Agent is running. For default instances, only specify the computer name: MyComputer. For named instances, use the format ComputerName\InstanceName.

Parameter properties

Type:

String[]

Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

ByName
Position:2
Mandatory:False
Value from pipeline:True
Value from pipeline by property name:False
Value from remaining arguments:False

-TrustServerCertificate

Indicates whether the channel will be encrypted while bypassing walking the certificate chain to validate trust.

In v22 of the module, the default is $true (for compatibility with v21). In v23+ of the module, the default value will be '$false', which may create a breaking change for existing scripts.

This parameter is new in v22 of the module.

Parameter properties

Type:SwitchParameter
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Outputs

System.Object