Using Parameters in an Instance Configuration File

Article
12/03/2008

If you configure an instance of Notification Services using an XML instance configuration file (ICF), you can use parameters to make the ICF more secure, portable, and easy to update. You also can pass values from the ICF into application definition files (ADFs).

If you configure an instance of Notification Services programmatically, there are no parameter objects. You can use variables if you want a single place to update a value for the instance definition and application definitions.

Notification Services Parameters

Notification Services allows you to use parameters in place of element values. Using parameters can be beneficial for several reasons:

You can keep sensitive data out of the ICF and ADFs and provide the values only when creating or updating the instance.
You can define a parameter value one time and use it in multiple elements.
You can make instance and application updates easier by placing values that are likely to change in one place.

Within an ICF or ADF, a parameter to be replaced looks like this: %MyParam%. This is the parameter name surrounded by percent characters. When you define a value for the parameter, you specify the name (MyParam) and a value for the parameter, such as MyServer.

When you create or update the instance, Notification Services replaces the parameter (%MyParam%) with the value you specify (MyServer).

For the ICF, you can provide parameter values in the ParameterDefaults element, on the nscontrol command line, or in the SQL Server Management Studio dialogs used to create or update the instance. However, SQL Server Management Studio allows only one level of parameter substitution. For example, parameter A can reference parameter B only if B does not itself reference another parameter.

Defining Parameter Defaults in the ICF

You can provide values for ICF parameters in the ICF's ParameterDefaults element. Notification Services reads the parameter names and values from this element and then replaces the corresponding parameters with the specified values.

For example, you can use a parameter for a file path common to multiple elements. You can name this parameter BaseDirPath and create the following elements in your ICF:

<BaseDirectoryPath>%BaseDirPath%\Stock</BaseDirectoryPath>
...
<AssemblyName>%BaseDirPath%\SMS.dll</AssemblyName>

You can then provide a value for %BaseDirPath% as follows:

<ParameterDefaults>
    <Parameter>
        <Name>BaseDirPath</Name>
        <Value>C:\NS</Value>
    </Parameter>
</ParameterDefaults>

When you create or update the instance, Notification Services replaces each occurrence of %BaseDirPath% in the ICF with the string "C:\NS". This is logically the same as using the following elements in your ICF:

<BaseDirectoryPath>C:\NS\Stock</BaseDirectoryPath>
...
<AssemblyName>C:\NS\SMS.dll</AssemblyName>

Defining Parameter Values When Creating and Updating an Instance

If you want to keep parameter values out of the ICF, you can provide values when creating or updating the instance or in environment variables. For example, if you use the nscontrol command-prompt utility to create the instance, you can provide user name and password values on the command line.

In this example, your delivery channel requires a user name and password. You do not want to store these in the ICF, so you use parameters:

<DeliveryChannel>
    <DeliveryChannelName>MyChannel</DeliveryChannelName>
    <ProtocolName>MyProtocol</ProtocolName>
    <Arguments>
        <Argument>
            <Name>UserName</Name>
            <Value>%User%</Value>
        </Argument>
        <Argument>
            <Name>Password</Name>
            <Value>%Pwd%</Value>
        </Argument>
    </Arguments>
</DeliveryChannel>

You can then provide values for the parameters on the command line:

nscontrol create -in "C:\NS\InstanceConfig.xml" User=Bob
    Pwd=bOb-P@sWd

You also can provide parameter values if you create or update the instance using SQL Server Management Studio.

Parameter Value Precedence

It is possible to define a value for the same parameter in the ParameterDefaults section, as an environment variable, and when creating or updating the instance. For this reason, there is precedence between parameter values:

Parameter values provided when creating or updating the instance will override values provided in environment variables and in the ParameterDefaults section.
Environment variables override ParameterDefaults values.
ParameterDefaults values have the lowest priority.

Passing Parameters to an ADF

Within the ICF, you use the Application element to describe an application hosted by the instance. The Application element has a Parameters child element. You can use this child element to define parameter values for the ADF.

For example, in the ADF you must define which servers run the hosted event providers, generator, and distributors. You do this via SystemName elements in the ADF. If you run all of these components on one server and you want to define the server name when you create the instance, you can use parameters in the ADF:

<HostedProvider>
    ...
    <SystemName>%ApplicationServer%</SystemName>
...
<Generator>
    <SystemName>%ApplicationServer%</SystemName>
...
<Distributor>
    <SystemName>%ApplicationServer%</SystemName>

You can then define a value for this parameter in the Application element of the ICF:

<Application>
    ...
    <Parameters>
        <Parameter>
            <Name>ApplicationServer</Name>
            <Value>Server01</Value>
        </Parameter>
    </Parameters>
</Application>

When you create the instance, Notification Services replaces each occurrence of %ApplicationServer% in the ADF with the value Server01.

You can also provide parameter values for the ADF in the ParameterDefaults element of the ADF.

You can combine these substitution methods as needed. For example, if you were to use a parameter, such as %AppServer%, for the ApplicationServer value, you could provide a value for %AppServer% on the command line.

Using Parameters in an Instance Configuration File

Notification Services Parameters

Defining Parameter Defaults in the ICF

Defining Parameter Values When Creating and Updating an Instance

Parameter Value Precedence

Passing Parameters to an ADF

See Also

Concepts

Other Resources

Help and Information

Additional resources