Using Parameters in an Application Definition File (ADF)

If you define a Notification Services application in an XML application definition file (ADF), you can use parameters to make the ADF more secure, portable, and easy to update. You also can pass values in from an instance configuration file (ICF) to ADFs.

If you define an application programmatically, there are no parameter objects. You can use variables if you want a single place to update a value for an application.

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 application definition and provide the values only when creating or updating the application.
• 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 ADF, a parameter to be replaced looks like this: %MyParam%. This is the parameter name surrounded by percent characters, which is similar to an environment variable. When you define a value for the parameter, you specify the name (MyParam) and a value for the parameter, such as MyServer. Like environment variables, parameter names are not case-sensitive.

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

For the ADF, you can provide parameter values in the ADF's ParameterDefaults element you can pass values from the ICF to the application by defining parameter names and values in the Application section of the ICF.

Defining Parameter Defaults in the ADF

You can provide values for ADF parameters in the ADF'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 ADF:

<BaseDirectoryPath>%BaseDirPath%\Stock</BaseDirectoryPath>
...
<AssemblyName>%BaseDirPath%\MyContentFormatter.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 ADF with the string "C:\NS". This is logically the same as using the following elements in your ADF:

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

Passing Parameters from an ICF

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 by means of 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".

Passing Parameters When Compiling an Instance

If you want to keep parameter values out of the ADF and 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 an instance of Notification Services, you can provide user name and password values on the command line.

To pass these values to the ADF, you must use parameters within the Application section of the ICF. Using the example above, instead of defining the application server in the ICF, we can use the parameter %Server%, as shown in this code:

<Application>
    ...
    <Parameters>
        <Parameter>
            <Name>ApplicationServer</Name>
            <Value>%Server%</Value>
        </Parameter>
    </Parameters>
</Application>

Then, on the command line you can provide values for the parameter:

nscontrol create -in "C:\NS\InstanceConfig.xml" Server=Server01

When you create or update the instance, the value Server01 replaces %Server% in the ICF. Server01 then replaces all occurrences of %ApplicationServer% in the ADF.

You can also pass parameters to the ADF when using SQL Server Management Studio to create and update instances of Notification Services. 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.

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 have the highest precedence and will override values provided in environment variables and in the ParameterDefaults section.
• Environment variables override ParameterDefaults values.
• ParameterDefaults values have the lowest priority.

See Also

Concepts

Using Parameters in an Instance Configuration File

Other Resources

ParameterDefaults Element (ADF)
Parameter Element (ADF)
ParameterDefaults Element (ICF)
nscontrol Utility
Defining Notification Services Applications
Configuring Instances of Notification Services

Help and Information

Getting SQL Server 2005 Assistance