SqlAgentAlert

Parameters

Parameter	Attribute	DataType	Description	Allowed Values
InstanceName	Key	System.String	The name of the SQL Server instance to be configured. Default value is 'MSSQLSERVER'.
Name	Key	System.String	The name of the SQL Server Agent alert.
Credential	Write	System.Management.Automation.PSCredential	Specifies the credential to use to connect to the SQL Server instance. If parameter *Credential' is not provided then the resource instance is run using the credential that runs the configuration.
Ensure	Write	System.String	Specifies if the SQL Server Agent alert should be present or absent. Default value is 'Present'.	Present, Absent
MessageId	Write	System.Int32	The message id of the SQL Server Agent alert. Valid range is 1 to 2147483647. Cannot be used together with Severity.
Port	Write	System.UInt16	Specifies the TCP port number to use when connecting to the SQL Server instance. This parameter is only applicable when connecting via TCP/IP. If not specified for a named instance, the SQL Server Browser service will be used to determine the port. For default instances, port 1433 is used by default.
Protocol	Write	System.String	Specifies the network protocol to use when connecting to the SQL Server instance. Valid values are 'tcp' for TCP/IP, 'np' for Named Pipes, and 'lpc' for Shared Memory. If not specified, the connection will use the default protocol order configured on the client.	tcp, np, lpc
ServerName	Write	System.String	The host name of the SQL Server to be configured. Default value is the current computer name.
Severity	Write	System.Int32	The severity of the SQL Server Agent alert. Valid range is 1 to 25. Cannot be used together with MessageId.
Reasons	Read	SqlReason[]	Returns the reason a property is not in desired state.

Description

The SqlAgentAlert DSC resource is used to create, modify, or remove SQL Server Agent alerts.

An alert can be switched between a system-message–based alert and a severity-based alert by specifying the corresponding parameter. The alert type will be switched accordingly.

The built-in parameter PSDscRunAsCredential can be used to run the resource as another user. The resource will then authenticate to the SQL Server instance as that user. It is also possible to use impersonation via the Credential parameter.

Requirements

• Target machine must be running Windows Server 2012 or later.
• Target machine must be running SQL Server Database Engine 2012 or later.
• Target machine must have access to the SQLPS PowerShell module or the SqlServer PowerShell module.

Known issues

All issues are not listed here, see here for all open issues.

Property Reasons does not work with PSDscRunAsCredential

When using the built-in parameter PSDscRunAsCredential the read-only property Reasons will return empty values for the properties Code and Phrase. The built-in property PSDscRunAsCredential does not work together with class-based resources that use advanced types, such as the Reasons parameter.

Using Credential property

SQL Authentication and Group Managed Service Accounts are not supported as impersonation credentials. Currently, only Windows Integrated Security is supported.

For Windows Authentication the username must either be provided with the User Principal Name (UPN), e.g., [email protected], or, if using a non‑domain account (for example, a local Windows Server account), the username must be provided without the NetBIOS name, e.g., username. Using the NetBIOS name, for example DOMAIN\username, will not work.

See more information in Credential Overview.

Examples

Example 1

This example shows how to ensure that the SQL Agent Alert Sev17 exists with the correct severity level, and SQL Agent Alert Msg825 with the correct message id.

Configuration Example
{
    Import-DscResource -ModuleName 'SqlServerDsc'

    node localhost
    {
        SqlAgentAlert 'Add_Sev17'
        {
            Ensure       = 'Present'
            Name         = 'Sev17'
            ServerName   = 'TestServer'
            InstanceName = 'MSSQLServer'
            Severity     = '17'
        }

        SqlAgentAlert 'Add_Msg825'
        {
            Ensure       = 'Present'
            Name         = 'Msg825'
            ServerName   = 'TestServer'
            InstanceName = 'MSSQLServer'
            MessageId    = '825'
        }
    }
}

Example 2

This example shows how to ensure that the SQL Agent Alert Sev17 does not exist, or that the SQL Agent Alert Msg825 does not exist.

Configuration Example
{
    Import-DscResource -ModuleName 'SqlServerDsc'

    node localhost
    {
        SqlAgentAlert 'Remove_Sev17'
        {
            Ensure       = 'Absent'
            Name         = 'Sev17'
            ServerName   = 'TestServer'
            InstanceName = 'MSSQLServer'
        }

        SqlAgentAlert 'Remove_Msg825'
        {
            Ensure       = 'Absent'
            Name         = 'Msg825'
            ServerName   = 'TestServer'
            InstanceName = 'MSSQLServer'
        }
    }
}