nscontrol export Command

  • Article

Creates an XML instance configuration file (ICF) and one or more XML application definition files (ADFs) (one per application) by exporting the metadata from the databases. The resulting files are valid definitions of the instance and applications at the time that you run the export command. You can use this information to back up your instance and application definitions or to generate files that you can use to create or update the instance.

Syntax

nscontrol export 
    [-nologo]
    [-help] 
        -name instanceName
    [-server databaseServer]
    [-sqlusername sqlUserName -sqlpassword sqlPassword]
    [-out directory]
    [-force]

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 from which to create configuration and application definition files.

  • -serverdatabaseServer
    Is the name of the server that hosts the instance and application databases. Provide this argument only if the instance is not registered on the local computer. If the instance is registered and you provide the -server argument, the registry values for the instance are ignored.

    If you are using a named instance of SQL Server to host the instance database, specify the server name and the instance name using the format <servername>\<instancename>.

  • -sqlusernamesqlUserName
    Is the SQL Server login used to connect to SQL Server.

    Important

    Windows Authentication is more secure than SQL Server Authentication. Whenever possible, use Windows Authentication.

    If you are using SQL Server Authentication to connect to SQL Server, specify a login using this argument. Also specify a password using the sqlpassword argument.

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

  • -sqlpasswordsqlPassword
    Is the password that is associated with the -sqlusername login. You should only use this argument when connecting using SQL Server Authentication.
  • -outdirectory
    Is the directory in which to write the files. The default directory is the current directory.
  • -force
    Specifies to overwrite existing files of the same name in the output directory.

Remarks

You can use the nscontrol export command while the instance is running. You do not need to disable or stop the instance.

The resulting configuration file is named <instance_name>.config.xml. Each resulting ADF is named <instance_name>.<application_name>.adf.xml.

The nscontrol export command writes the files using UTF-8 encoding. To export the configuration and application definition files using other encodings, use the Export command in SQL Server Management Studio.

The nscontrol export command does not recreate the original configuration and application definition files. It creates files that contain the current instance and application settings, including values that may have been provided through replaceable parameters. For this reason, we recommend that you keep the original configuration and application definition files and use nscontrol export if you need to determine current instance and application settings.

The nscontrol export command modifies the ApplicationDefinitionFilePath values in the configuration file to point to the exported ADFs; this path is modified so that the configuration file can be used immediately. All other path settings, including BaseDirectoryPath, are left unmodified because they can point to other files needed by the instance, such as content formatter files.

Permissions

The account used to run nscontrol export, or the SQL Server login specified by the -sqlusername argument, can obtain database permissions through membership in the NSReader database role in individual application and instance databases. Members of the db_owner database role and the sysadmin and dbcreator fixed server roles also can run nscontrol export.

The account must also have permission to execute the Notification Services binary files; this permission is granted to members of the Administrators and SQLServerNotificationServicesUser Windows groups.

Examples

The following examples illustrate how to export metadata to XML files.

A. Exporting files to the current directory

This example shows how to export instance and application information for the StockInstance instance. The nscontrol utility uses Windows Authentication to connect to SQL Server and writes the configuration and application definition files to the current directory. If the files already exist, nscontrol displays an error message.

nscontrol export -name StockInstance

B. Exporting files to a specific directory, overwriting existing files

This example shows how to specify a directory for the resulting instance and application files. It also shows how to use the –force argument to overwrite any existing files of the same name.

The nscontrol utility uses Windows Authentication to connect to SQL Server.

nscontrol export -name StockInstance -out "C:\NS\Export" -force

C. Exporting files from an administration computer

This example shows how to export instance and application information when the instance is not registered on the computer. You must specify the SQL Server instance name using the –server argument. This example also specifies an output directory and specifies to overwrite existing files of the same name.

The nscontrol utility uses Windows Authentication to connect to SQL Server.

nscontrol export -name StockInstance -server nsuetest 
    -out "C:\NS\Export" -force

D. Exporting files using SQL Server Authentication

This example shows how to export instance information for the StockInstance instance using SQL Server Authentication to connect to SQL Server. The configuration and application definition files are created in the C:\NS\Export directory, but are not overwritten if they already exist.

nscontrol export -name StockInstance -out "C:\NS\Export" 
    -sqlusername SqlUser -sqlpassword sQl-P@sWd

See Also

Reference

nscontrol Utility

Other Resources

How to: View Notification Services Version Information

Help and Information

Getting SQL Server 2005 Assistance

Change History

Release History

5 December 2005
New content:
  • Added information about the SQLServerNotificationServicesUser Windows group.