nscontrol register Command

Creates or updates registry entries for an instance of Notification Services, creates performance counters for the instance, and optionally creates a Microsoft Windows service to run the instance.

Syntax

nscontrol register 
    [-nologo]
    [-help]
    -name instanceName
    [-server databaseServer]
    [-service
        [-serviceusername NSServiceUserName [-servicepassword NSServicePwd]
        [-sqlusername NSServiceSqlUserName  -sqlpassword NSServiceSqlPwd]
        [-argumentkey key]]

Arguments

• -nologo
  Suppresses the product and version statement that appears when you run an nscontrol command.

• -help
  Displays the command syntax.

• -nameinstanceName
  Is the name of the instance to register.

• -serverdatabaseServer
  Is the name of the server that hosts the instance database. If you use a named instance of SQL Server to host the instance database, you must specify both the server name and the instance name, using the format <servername>\<instancename>. If you do not specify a database server name, nscontrol register uses the local server name.

• -service
  Creates the NS$instance_name Windows service that controls the instance of Notification Services on the server.

  You typically use the -server argument on any server that runs a hosted event provider, generator, or distributor. You do not need to use this argument on servers that run only subscription management interfaces, non-hosted event providers, or management applications.

  If you are hosting the Notification Services engine in your own application, do not use the -service argument. For more information about hosting the engine, see Hosting the Notification Services Engine.

• -serviceusernameNSServiceUserName
  Is the Windows account that the Windows service uses to access local and remote resources. If you are using Windows Authentication, the Windows service also uses this account to log in to SQL Server and access instance and application databases.

  For local and domain accounts, this argument must be used together with the -servicepassword argument. Built-in accounts such as NetworkService do not have passwords.

  In Microsoft Windows XP, if -serviceusername and -servicepassword are not specified, the default account NT AUTHORITY\NetworkService is used. For other operating systems, -serviceusername and -servicepassword are required.

  Note

  For security reasons, the service account should run with minimum permissions, not as an administrator or as the LocalSystem service account. For more information, see Configuring Windows Accounts for an Instance of Notification Services.

  If you are using Windows Authentication, this account must have permissions in the instance and application databases. For more information, see Configuring SQL Server Permissions for an Instance of Notification Services.

• -servicepasswordNSServicePwd
  Is the password that is associated with serviceusername. This argument must be used with the -serviceusername argument.

• -sqlusernameNSServiceSqlUserName
  Is the SQL Server login that the NS$<instance_name> Windows service uses to connect to SQL Server.

  If you are using SQL Server Authentication to connect to SQL Server, you must specify both the -sqlusername and -sqlpassword arguments.

  If you are using Windows Authentication, do not specify the -sqlusername and -sqlpassword arguments.

  Note

  If you assign a SQL Server user name and password to the service, this information is encrypted and stored in the registry. To avoid storing this information, use Windows Authentication instead.

• -sqlpasswordNSServiceSqlPwd
  Is the password associated with the sqlusername login. This argument must be used together with the sqlusername argument.

• -argumentkeykey
  Is the value used to encrypt delivery channel and event provider arguments that are stored in Notification Services databases. The key is used only if the –service argument is specified; otherwise, the key is ignored.

  If you register the instance using an encryption key, you must use the same key when you create and update the instance. To do this, the EncryptArguments value in the configuration file must be true.

  The key is a string of up to 2500 characters. nscontrol register encrypts the key value and stores it in the registry; this is required to allow the NS$instance_name Windows service to read the encrypted arguments.

  You cannot change the key after creating the instance, which is done with nscontrol create or the New Notification Services Instance command in SQL Server Management Studio.

Remarks

The nscontrol register command must be run locally. You cannot register Notification Services on a remote server.

If you use SQL Server Authentication to connect to SQL Server, and if you must update the SQL Server user name or password used by the service, you must change the login information using nscontrol register or the Register dialog for Notification Services in SQL Server Management Studio. Notification Services encrypts the user name and password and stores them in the registry where only the administrators and the Windows service have access.

If you specify an encryption key value using -argumentkey, the nscontrol register command encrypts the key and stores it in the registry. The key is secured so that only members of the local Administrators group and the account that the NS$instance_name service runs under can read the key.

Permissions

The account used to run nscontrol register must also have permission to execute the Notification Services binary files; this permission is granted to members of the Administrators and SQLServerNotificationServicesUser Windows groups. If you are creating a Windows service and performance counters, the account must be a member of the Administrators group.

For information about the permissions required by the NS$instance_name Windows service for Notification Services, see Securing Notification Services.

Examples

The following examples illustrate three different forms of registering an instance.

A. Register an instance and create a Windows service

This example shows how to register an instance named StockInstance, using Windows Authentication to connect to SQL Server. Registering the instance using the following arguments creates a Windows service for the instance, defines the user name and password used by the Windows service to access SQL Server (and to start and access Windows resources), and provides the name of the SQL Server instance that hosts the databases.

nscontrol register -name StockInstance -server nsuetest -service 
    -serviceusername SvcAcct -servicepassword svC-P@sWd

B. Registering an instance without creating a Windows service

This example shows how to register an instance named StockInstance in the following scenarios:

• A subscription management interface or independent event provider is located on the server, but the server does not run a hosted event provider, generator, or distributor.
• The Notification Services engine that runs hosted event providers, generators, and distributors is hosted by a custom application, so the Windows service is not necessary.

In these scenarios, you must register the instance so that instance components can locate the databases, but you do not use the -server argument to create the Windows service.

You might also use this example to update the database server name in an existing registry entry.

nscontrol register -name StockInstance -server nsuetest

C. SQL Server Authentication

This example shows how to register an instance of Notification Services, create the Windows service, and provide a SQL Server Authentication that the service uses to connect to SQL Server. Note that the service requires both a SQL Server account and password and a Windows account and password. The service uses the Windows permissions for startup and to access non-database resources, and uses the SQL Server account to access databases.

nscontrol register -name StockInstance -server nsuetest -service 
    -serviceusername SvcAcct -servicepassword svC-P@sWd 
    -sqlusername SqlUser -sqlpassword sQl-P@sWd

See Also

Reference

nscontrol Utility

Other Resources

Deploying an Instance of Notification Services
Updating Registry Information
EncryptArguments Element (ICF)
Hosting the Notification Services Engine

Help and Information

Getting SQL Server 2005 Assistance

Change History