The Instance Configuration File in Detail

As described earlier, to create an instance, you write an Instance Configuration File (ICF). I showed the ICF for the instance created in this chapter earlier, but we did not look at its contents.

Table 4.1 shows some of the key elements in the ICF. In this section, we'll take a closer look at each of these.

Table 4.1. XML Elements in the ICF

XML Element	Purpose
<NotificationServicesInstance>	Root element that defines the instance.
<InstanceName>	Name for the instance.
<ParameterDefaults>	Provides default values for parameters used in the ICF.
<SqlServerSystem>	Identifies the SQL Server on which the instance and application database objects will be created.
<Database>	Specifies the name of the database and schema in which the instance's database objects will be deployed when the ICF is compiled.
<Applications>	Lists the applications in the instance.
<Protocols>	Declares custom delivery protocols used in the instance.
<DeliveryChannels>	Defines the configured endpoints to which applications in the instance can send notifications.

Note

Many of the ICF elements are optional. Not every ICF you encounter will have all the elements shown in Table 4.1

The ICF in this chapter is basic and can be a starting point for any instance you create. My intent here is not to present an exhaustive reference of every XML element and option that the ICF supportsthe SQL-NS Books Online already do a great job of that. Instead, I'll introduce you to the key elements that you need to get started and mention some others that might be useful as you develop and deploy your own instances. Every element described here is also documented in detail in the SQL-NS Books Online. Here I simply describe the intended purpose of each element and how to use it; I do not cover the syntactical details such as naming restrictions and formats, which are covered in the SQL-NS Books Online.

In the following sections, we'll look at one piece of the ICF at a time. Each of these pieces is intended to highlight just a single part of the ICF content but will likely not compile by itself. I indicate missing code (code shown in other sections) by means of the ellipsis (...).

Parameters

Before actually delving into the code, I want to first expand on the notion of parameters in Notification Services source files. (You saw parameters used when examining the nscontrol create command line earlier.) Proper use of parameters allows you to make your instance and application definitions flexible, and makes administration tasks much easier.

Parameters are simply tokens in source files that the SQL-NS compiler substitutes with values you supply at compile time. Consider a case where parameters are useful: in the ADF, you have to specify the name of the server on which the application components (such as the generator) should run. If you put the server name directly in the ADF, you'd have to edit the ADF if you wanted to change it. Worse, if this server name was used in many places in the ICF and ADFs, you'd have to remember to find and change all of them.

Instead of putting the server name in the ADF directly, you can use a parameter: a token, such as %_NSServer_%. At the time of invoking the SQL-NS compiler, you'd have to specify a value for this parameter. The SQL-NS compiler then substitutes this value for every occurrence of %_NSServer_%. In SQL-NS ICFs and ADFs, any token between percent (%) signs is treated as a parameter.

By using a parameter for the server name, if you wanted to deploy the application components on a different server, you would have to pass a different value for the parameter when you invoked the compiler. You would not need to edit your ICF and ADFs; you could reuse them unmodified for several servers. Also, using a parameter ensures that all references to the server name would be changed at once.

Parameters used in the ICF are passed directly to the compiler, either as arguments to nscontrol create on the command line or as values typed into the parameters grid in the New Notification Services Instance dialog box in Management Studio. But these parameters are not automatically usable in the ADFs referenced by the ICF. Any parameters used in an ADF must be declared and assigned values when that ADF is referenced in the ICF. You'll see this done in the section "The Applications" (p. 109), which describes the <Application> element of the ICF. You can assign the value of an ICF parameter to an ADF parameter to "pass through" the ICF parameter to the ADF, as shown in Figure 4.8.

Figure 4.8. Parameters, the ICF, and the ADFs.

As shown in Table 4.1, the ICF schema defines an optional element called <ParameterDefaults> that allows you to specify default values for parameters. Parameters assume the default values as declared in the <ParameterDefaults> element, unless you specify different values when you invoke the SQL-NS compiler (regardless of whether you use the command-line or Management Studio tools). In the case of Management Studio, when you load an ICF in the New Notification Services Instance dialog box, the parameters grid is initialized with the default values from the ICF's <ParameterDefaults> element.

The <ParameterDefaults> element from this chapter's ICF is shown in Listing 4.2.

Listing 4.2. The <ParameterDefaults> element of the ICF

 <NotificationServicesInstance> ...   <ParameterDefaults>     <Parameter>       <Name>_SQLServer_</Name>       <Value>... Your SQL Server Name ...</Value>     </Parameter>     <Parameter>       <Name>_NSServer_</Name>       <Value>%COMPUTERNAME%</Value>     </Parameter>     <Parameter>       <Name>_InstanceBaseDirectoryPath_</Name>       <Value>C:\SQL-NS\Samples\MinimalMultiApplication</Value>     </Parameter>   </ParameterDefaults> ... </NotificationServicesInstance> 

Notice that on your system, default values for the SQL Server name and the instance base directory path will be customized for your environment. The parameter default values were obtained from the environment variable settings you made when you set up your development environment in Chapter 2 and were written into the ICF when it was generated from a template during the setup stage. Having the correct parameter default values for your environment in the ICF allowed you to create the instance in Management Studio without needing to alter any of the values in the parameters grid.

The value for the _NSServer_ parameter is obtained directly from the environment variable %COMPUTERNAME%. SQL-NS allows you to use environment variable values like this in the ICF. Because %COMPUTERNAME% is a standard environment variable that will be set on every system, we can safely use it. We could not use the other environment variables you created in Chapter 2 directly because they are set only when going through the command-line environment, not when you use Management Studio.

Note

If a parameter is used in the ICF, no value is supplied for it when the compiler is invoked, and no default is given; the ICF will not compile and you'll see an error message from the compiler.

The Root Element

The ICF is an XML document referencing the ICF schema with <NotificationServicesInstance> as the root element, as shown in Listing 4.3.

Listing 4.3. The Outline of the ICF

[View full width]

 <?xml version="1.0" encoding="utf-8"?> <NotificationServicesInstance xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http ://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.microsoft.com /MicrosoftNotificationServices/ConfigurationFileSchema"> ... </NotificationServicesInstance> 

The first line is the standard XML processing directive. Next is the root element, with all the namespace specifiers. Last is the closing tag for the root element. All the code in the rest of this chapter goes in between the open and close tags of this root element.

Note

The next sections of this chapter show this enclosing root element of the ICF, but without all the schema namespace specifiers. This is simply for brevity and readability; in a real ICF, the namespace specifiers should always be present.

The Instance Name and SQL Server

Inside the ICF's root element, the instance name and target SQL Server are specified by means of the <InstanceName> and <SqlServerSystem> elements, respectively. These are shown in Listing 4.4.

Listing 4.4. Specifying the Instance Name and SQL Server in the ICF

 <NotificationServicesInstance>   <InstanceName>MinimalMultiApplication</InstanceName>   ...   <SqlServerSystem>%_SQLServer_%</SqlServerSystem>   ... </NotificationServicesInstance> 

The SQL Server name is given as a parameter, %_SQLServer_%. When we compiled the ICF, the parameter was substituted with the correct value for the SQL Server name (if you used nscontrol create, the parameter value was passed in on the command line; if you used Management Studio, the parameter default value was used). On my system, the SQL Server is called PATHERNETMCE. With parameter substitution, the preceding code would be equivalent to

 <NotificationServicesInstance>   ...   <InstanceName>MinimalMultiApplication</InstanceName>   ...   <SqlServerSystem>PATHERNETMCE</SqlServerSystem>   ... </NotificationServicesInstance> 

The value in the <SqlServerSystem> element can also contain a SQL Server instance name if necessary. In my case, I specified a server name because I'm connecting to the default (unnamed) SQL Server instance. If you're using a named SQL Server instance, you could specify a SQL Server name of the form ServerName\InstanceName in the <SqlServerSystem> element.

The Database Element in the ICF

Like the ADF, the ICF can specify a <Database> element. The database and schema name supplied in this element control where the instance database objects are installed. Listing 4.5 shows the <Database> element from this chapter's ICF.

Listing 4.5. Specifying the Database and Schema Name in the ICF

 <NotificationServicesInstance>   ...      <Database>     <DatabaseName>MinimalMultiApplication</DatabaseName>     <SchemaName>NSInstance</SchemaName>   </Database>   ... </NotificationServicesInstance> 

In this chapter's sample, and the one in the previous chapter, the ICF and ADFs specified the same database name in their <Database> elements. This resulted in the instance and application database objects being deployed in the same database, isolated in different schemas.

In many cases, keeping all the objects in a single database is desirable, but you can also put them in separate databases if you prefer. To do this, specify different database names in the <Database> elements in the ICF and ADFs. If you do use more than one database, you must grant the SQL-NS engine permission to access each of them. To do this, repeat the steps outlined earlier in the "Granting Database Permissions" section (p. 93) for each database.

The <Database> element is optional in both the ICF and the ADF. If you omit the <Database> element from the ICF, the instance database objects will be created in the dbo schema in a dedicated database. The name of this database will be the instance name, followed by NSMain. For example, if we'd omitted the <Database> element in this chapter's ICF, the instance database objects would have been placed in a database called MinimalMultiApplicationNSMain. If you omit the <Database> element in an ADF, then the application's database objects will be placed in the dbo schema in another dedicated database. The name of this database will be the instance name, concatenated with the application name. For example, the dedicated database for the Application1 application in this chapter's instance would be called MinimalMultiApplicationApplication1 had we omitted the <Database> element from the ADF.

Note

Though I'm not showing them here, other subelements within the <Database> element allow you to customize how the databases are created. For example, you can specify filegroups for the data and log files, as well as the collation. See Chapter 12, "Performance Tuning," and the SQL-NS Books Online documentation for the <Database> element for more details.

The Applications

The instance is a container for a set of related applications, and the ICF lists those applications. The list appears in the <Applications> element, as shown in Listing 4.6.

Listing 4.6. Specifying the Applications in the Instance

 <NotificationServicesInstance>   ...   <Applications>     <Application>       <ApplicationName>Application1</ApplicationName>       <BaseDirectoryPath>         %_InstanceBaseDirectoryPath_%\Application1       </BaseDirectoryPath>       <ApplicationDefinitionFilePath>         ApplicationDefinition.xml       </ApplicationDefinitionFilePath>       <Parameters>         <Parameter>           <Name>_NSServer_</Name>           <Value>%_NSServer_%</Value>         </Parameter>         <Parameter>           <Name>_ApplicationBaseDirectoryPath_</Name>           <Value>%_InstanceBaseDirectoryPath_%\Application1</Value>         </Parameter>       </Parameters>     </Application>     <Application>       <ApplicationName>Application2</ApplicationName>       <BaseDirectoryPath>         %_InstanceBaseDirectoryPath_%\Application2       </BaseDirectoryPath>       <ApplicationDefinitionFilePath>         ApplicationDefinition.xml       </ApplicationDefinitionFilePath>       <Parameters>         <Parameter>           <Name>_NSServer_</Name>           <Value>%_NSServer_%</Value>         </Parameter>         <Parameter>           <Name>_ApplicationBaseDirectoryPath_</Name>           <Value>%_InstanceBaseDirectoryPath_%\Application2</Value>         </Parameter>       </Parameters>     </Application>   </Applications>     ...   </Applications>   ... </NotificationServicesInstance> 

The <Applications> element contains an <Application> element for each application in the instance. The fragment in Listing 4.6 shows the <Application> element for both applications in this chapter's instance.

The first subelement of <Application> is <ApplicationName>, which, as you might guess, specifies the name of the application. In this simple example, the application is called Application1, although you'd most likely have a more descriptive name for a real application.

The <BaseDirectoryPath> element specifies the root of the directory tree in which all the application's files are located. These files include the ADF and any supporting files required by the application. In this example, the value of the <BaseDirectoryPath> element is derived from a parameter value, %_InstanceBaseDirectoryPath_%.

This is because of the way I've chosen to lay out the files of the instance. I have one root directory for the entire instance, and every file belonging to the instance either exists in this directory or in a subdirectory off it. The parameter, _InstanceBaseDirectoryPath_, provides the name of the root directory of the instance. Each application is in a directory off this, named with the application name. So, Application1 is in %_InstanceBaseDirectoryPath_%\Application1.

Note that nothing in SQL-NS mandates this directory layout. This is just one that makes sense to me (and is common in many SQL-NS deployments I've seen).

The <ApplicationDefinitionFilePath> element specifies the path to and the name of the application's ADF, relative to the application's base directory path in the previous element. Because our ADF is located in the root of the application's directory, this is just a filename. When compiling the instance, SQL-NS goes through each of the application declarations and compiles the ADF, located by appending the <ApplicationDefinitionFilePath> to the <BaseDirectoryPath>.

The next element is the <Parameters> element. This is where the input parameters to the ADF are specified. Each contains a <Name> and <Value> subelement that contains, as you might expect, the name and the value of the parameter, respectively.

Because each application has its own <Parameters> element, you can specify different values for the same parameter name in each application. In the example shown here, the first parameter, _NSServer_, is simply a pass-through of the value of the instance parameter with the same name. So, %_NSServer_% is specified as the value expression. The second parameter, _ApplicationBaseDirectoryPath_, is derived from the instance base directory path. This is essentially the same value as that given for the <BaseDirectoryPath> element, so you might wonder why it's being created twice.

When specified as a value for <BaseDirectoryPath>, it's simply a value for an ICF element. Here it's being specified as a value to a parameter that will be passed into the ADF. This is needed because the elements in the ADF use this to specify the location of various files. Unless passed in as an explicit parameter, the ADF has no way to refer to the value given for <BaseDirectoryPath>. It's unfortunate that we have to derive this value twice, because if we changed it, we'd have to change it in two places. It would be nice if SQL-NS allowed us to create new parameters (a bit like local variables) in the ICF. However, this facility doesn't exist, so we have to live with the limitation.

Delivery Channels

The last ADF element we'll look at in this chapter is the <DeliveryChannels> element. As described earlier, a delivery channel is simply a representation of a named, configured endpoint to which notifications can be sent. Every delivery channel uses a delivery protocol to communicate with the endpoint, and this can be one of the built-in protocols, or a custom delivery protocol, developed by you or a third party. Listing 4.7 shows a sample definition of a delivery channel in the <DeliveryChannels> element.

Listing 4.7. Specifying the Delivery Channels

 <NotificationServicesInstance>   ...   <DeliveryChannels>     <DeliveryChannel>       <DeliveryChannelName>FileChannel</DeliveryChannelName>       <ProtocolName>File</ProtocolName>       <Arguments>         <Argument>           <Name>FileName</Name>           <Value>             %_InstanceBaseDirectoryPath_%\FileNotifications.txt           </Value>         </Argument>       </Arguments>     </DeliveryChannel>   </DeliveryChannels>     ...   </DeliveryChannels> </NotificationServicesInstance> 

Each delivery channel is defined in a <DeliveryChannel> element. Subelements specify a name for the delivery channel (<DeliveryChannelName>) and the name of the protocol the delivery channel uses to deliver messages (<ProtocolName>). In this case, the delivery channel uses the File protocol, which is one of the built-in protocols shipped with SQL-NS. If you were using a custom developed delivery protocol, you would have to declare it, give it a name, and then reference that name here. Chapter 10 shows examples of using custom delivery protocols.

Finally, the <DeliveryChannel> element contains a list of named arguments in the <Arguments> element. The values of these arguments are passed to the delivery protocol implementation when the delivery channel is initialized.