New-SqlAvailabilityGroupListener

Creates a new availability group listener and attaches it to an existing availability group.
New-SqlAvailabilityGroupListener [-Name*] <string> [-InputObject*] <AvailabilityGroup> [-DhcpSubnet <string>] [-Port<int>] [-Script] [-StaticIp <string[]>] [<CommonParameters>]
New-SqlAvailabilityGroupListener [-Name*] <string> [[-Path] <string>] [-DhcpSubnet <string>] [-Port <int>][-Script] [-StaticIp <string[]>] [<CommonParameters>]

The New-SqlAvailabilityGroupListener cmdlet creates a new availability group listener, and attaches it to an availability group. It takes parameters that identify the availability group and the IP addresses. This cmdlet can be executed only at the server instance that hosts the primary replica.

Parameters
-DhcpSubnet <string>

Specifies that the listener should use DHCP on the subnet specified by the argument. This argument should be an IPv4 Address and subnet mask in slash notation, for example 192.168.0.1255.255.255.0.StaticIp and DhcpSubnet are mutually exclusive options.

-InputObject <AvailabilityGroup>

  • This value is required
  • Accepts pipeline input ByValue

The Availability Group object of the availability group to which we should attach the listener.

-Name <string>

  • This value is required

The name of the listener.

-Path <string>

The path to the availability group. The new listener will attach to the availability group specified by this path. This is an optional parameter. If not specified, the value of this parameter defaults to the current working location.

-Port <int>

  • Default value is 65535

The port that the listener will use to listen for connections. The default port is TCP port 1433. If you have security concerns, we recommend using a different port number.

-Script [<SwitchParameter>]

Outputs a Transact-SQL script that performs the task executed by this cmdlet.

-StaticIp <string[]>

Specifies that the listener should be configured with the static IP addresses specified by the argument. This argument should be a list of strings. Each of these strings can be either an IPv4 address and subnet mask in slash notation, or an IPv6 address.StaticIp and DhcpSubnet are mutually exclusive options.

<CommonParameters>

This cmdlet supports the common parameters: Verbose, Debug,ErrorAction, ErrorVariable, WarningAction, WarningVariable,OutBuffer, PipelineVariable, and OutVariable.

Inputs

Microsoft.SqlServer.Management.Smo.AvailabilityGroup

Examples
  1. This command creates an availability group listener named ‘MyListener’ for the availability group ‘MyAg’:
    C:PS> New-SqlAvailabilityGroupListener -Name MyListener -Path SQLSERVER:SQLPrimaryServerInstanceNameAvailabilityGroupsMyAg
    

    This listener will use DHCP to acquire a virtual IP address. This command must be executed on the server instance that hosts the primary replica.

  2. This command creates an availability group listener named ‘MyListener’ for the availability group ‘MyAg’:
    C:PS> New-SqlAvailabilityGroupListener -Name MyListener -Path SQLSERVER:SQLPrimaryServerInstanceNameAvailabilityGroupsMyAg -Port 1434
    

    This listener will use DHCP to acquire a virtual IP address and will listen for connections on port 1434. This command must be executed on the server instance that hosts the primary replica.

  3. This command creates an availability group listener named ‘MyListener’ for the availability group ‘MyAg’:
    C:PS> New-SqlAvailabilityGroupListener -Name MyListener -DhcpSubnet '192.169.0.1/255.255.252.0' -Path SQLSERVER:SQLPrimaryServerInstanceNameAvailabilityGroupsMyAg
    

    This listener will use DHCP on the specified subnet to acquire a virtual IP address. This command must be executed on the server instance that hosts the primary replica.

  4. This command creates an availability group listener named ‘MyListener’ for the availability group ‘MyAg’:
    C:PS> New-SqlAvailabilityGroupListener -Name MyListener -StaticIp '192.168.3.1/255.255.252.0' -Path SQLSERVER:SqlComputerInstanceAvailabilityGroupsMyAg
    

    This listener will use the IPv4 address passed to the -StaticIp parameter as its virtual IP address.

  5. This command outputs a Transact-SQL script that creates an availability group listener named ‘MyListener’ for the availability group ‘MyAg’:
    C:PS> New-SqlAvailabilityGroupListener -Name MyListener -Path SQLSERVER:SqlComputerInstanceAvailabilityGroupsMyAg -Script
    

    The listener is not actually created by this command.

Additional Notes
 
Related Links