Extending the Development Environment

This section describes how to extend the development environment used in this book to allow you to build new instances and applications of your own. The instructions in this section walk you through setting up the code and build scripts for a new SQL-NS instance with one application. You can follow this same procedure whenever you work on a new SQL-NS project. Extending this book's development environment, instead of designing your own environment from scratch, has the advantage that you can continue to use the same scripts and techniques you've become familiar with as you've worked through the examples in this book.

Caution

The instructions in this section assume you have set up the development environment for this book's samples according to the instructions given in Chapter 2. It's especially important that you successfully complete the instructions in the section "Customizing the Source Files for Your Environment," p. 39, in Chapter 2 before you proceed with the instructions given here.

Note that any new SQL-NS instances you create following the instructions in this section will have the same configuration as this book's samples, including the accounts used to run the SQL-NS engine and connect to the SQL Server.

Creating a Root Directory for New Instances

Assuming you do not want to create your new instances alongside this book's sample instances in the Samples directory, you should create a new top-level directory beneath C:\SQL-NS. Within this new directory, you can later create subdirectories for each instance you develop.

You can choose any name for the new directory, but for the purposes of the instructions given here, I will assume it's called NewInstances (if you choose a different name, replace NewInstances appropriately in all the following instructions). This directory must be created immediately beneath C:\SQL-NS, at the same level as the Samples directory.

You can create the directory for your new instances with the following command:

 mkdir C:\SQL-NS\NewInstances 

Alternatively, if you don't mind creating new instances directly in the Samples directory, you do not need to create a new directory. Simply replace C:\SQL-NS\NewInstances with C:\SQL-NS\Samples in all the subsequent instructions.

Creating the Directories and Files for a New Instance

Before creating the directories and files for a new instance, you must decide on the instance name and the name of the application in it. In the instructions given in this section, the instance name is assumed to be MyNewInstance, and the single application in the instance is assumed to be called MyNewApplication. When you invoke the commands described here to create a new instance of your own, replace these names with the names you've chosen.

Use the following instructions to create the directories and files for a new instance:

1.	Create a new directory for the instance using the following command: mkdir C:\SQL-NS\NewInstances\MyNewInstance
2.	Copy the files and subdirectories from the Samples\Minimal directory into the NewInstances\MyNewInstance directory using the following command: xcopy /ev C:\SQL-NS\Samples\Minimal\*.* C:\SQL-NS\NewInstances\MyNewInstance
3.	Rename the Application1 application directory to the name of your application using the following command: rename C:\SQL-NS\NewInstances\MyNewInstance\Application1 MyNewApplication

After the directory structure and the files for the new instance have been created using the preceding instructions, you must edit some of the files before you can run the build scripts. Use the following instructions to make the required changes:

1.	Open the file C:\SQL-NS\NewInstances\MyNewInstance\Scripts\setenv.cmd in a text editor. The file contains the following text: call ..\..\..\Common\setenv.cmd set INSTANCE_NAME=Minimal set INSTANCE_BASE_DIRECTORY_PATH=%SQLNS_BASE_DIRECTORY_PATH%\Samples\Minimal set INSTANCE_DATABASE=%INSTANCE_NAME%
2.	In the second line, change Minimal (shown in boldface font) to the name of your instance. In the case of the instance name, MyNewInstance, this line should read: set INSTANCE_NAME=MyNewInstance
3.	In the third line, replace Samples\Minimal (also shown in boldface font) with the name of the directory that contains your new instance. Note that the Samples part should be replaced with the name of the top-level directory you created for all new instances and the Minimal part should be replaced with the name of this particular instance's subdirectory. Continuing with the example names used so far, this line should be changed to: set INSTANCE_BASE_DIRECTORY_PATH=%SQLNS_BASE_DIRECTORY_PATH%\NewInstances\MyNewInstance
4.	The default configuration for the new instance will deploy the instance database objects into a database with the same name as the instance. If you want to use a different database name, change the fourth line to set the INSTANCE_DATABASE environment variable to the desired database name. If you want to use the instance name as the database name, no changes are needed to the fourth line.
5.	Save your changes to C:\SQL-NS\NewInstances\MyNewInstance\Scripts\setenv.cmd.
6.	Open the file C:\SQL-NS\NewInstances\MyNewInstance\SQLPermissions.sql in a text editor.
7.	Replace the word Minimal in the USE directive on the first line with the name of your instance database. For example, if the instance database name is MyNewInstance, the first line of the file should read: USE MyNewInstance Unless you chose a different name in step 4, the database name is the instance name.
8.	Save your changes to C:\SQL-NS\NewInstances\MyNewInstance\SQLPermissions.sql.
9.	Open the ICF C:\SQL-NS\NewInstances\MyNewInstance\InstanceConfiguration.xml in a text editor.
10.	Change the value of the <InstanceName> element from Minimal to the name of your instance. In the case of the instance name MyNewInstance, the <InstanceName> element should be declared as follows: <InstanceName>MyNewInstance</InstanceName>
11.	Search for Application1 in the file and replace all occurrences with the name of your application, MyNewApplication. You should find three occurrences.
12.	Change the value of the <DatabaseName> element from Minimal to the name of your instance database. Unless you chose a different name in step 4, the database name is the instance name.
13.	Save your changes to C:\SQL-NS\NewInstances\MyNewInstance\InstanceConfiguration.xml.
14.	Open the ADF C:\SQL-NS\NewInstances\MyNewInstance\MyNewApplication\ApplicationDefinition.xml in a text editor.
15.	Within the <Database> element, you'll need to change the values of the <DatabaseName> and <SchemaName> elements. The configuration scripts assume the instance and application database objects are located in the same database, so you must set the <DatabaseName> element in the ADF to the same value you used for in the <DatabaseName> element in the ICF in step 12. You can set the <SchemaName> element to any value you choose. It's a common convention to use the application name, but this is not a requirement. You'll need to use the schema name you specify here to qualify the names of the application database objects as you add content to the ADF later on. Given the example names we've been working with, the <Database> element in the ADF should look like this: <Database> <DatabaseName>MyNewInstance</DatabaseName> <SchemaName>MyNewApplication</SchemaName> </Database>
16.	Save your changes to C:\SQL-NS\NewInstances\MyNewInstance\MyNewApplication\ApplicationDefinition.xml.

Building and Running the New Instance

After making the changes described in the previous section, you can use the build scripts to compile the new instance and then start it running. Use the following instructions to do this:

1.	Open a Notification Services Command Prompt and navigate to the Scripts directory of the new instance using the following command: cd /d C:\SQL-NS\NewInstances\MyNewInstance\Scripts
2.	Run create.cmd to create the new instance. This creates the instance and application database objects.
3.	Run register.cmd to register the new instance.
4.	Run grant_permissions.cmd to grant the required database and filesystem permissions.
5.	Run enable.cmd to enable the instance.
6.	Start the instance using the following command: net start NS$MyNewInstance

At this point, the new instance is running, although it doesn't do much because it doesn't contain any real code. But you now have a skeleton SQL-NS instance and application to serve as a basis for your development work.

Note

The build scripts described here use the nscontrol command-line tools, but you can also work with the new instance using the graphical tools in Management Studio, as described in Chapter 4.

Adding Code to the New Instance

The ICF for the new instance is in the file C:\SQL-NS\NewInstances\MyNewInstance\InstanceConfiguration.xml. The ADF for the single application, MyNewApplication, is in the file C:\SQL-NS\NewInstances\MyNewInstance\MyNewApplication\ApplicationDefinition.xml. You can edit these files to add new code.

Tip

If you use Management Studio as your XML editor when adding code to the ICF and ADF, you can take advantage of its built-in syntax-checking and element auto-completion features. These can make adding new code much more efficient and less error prone. For details on how to enable these features, see the sidebar, "Support for ADF and ICF Editing in Management Studio," (p. 139) in Chapter 5, "Designing and Prototyping an Application."

As you build the functionality of your SQL-NS instance, I encourage you to use the incremental development approach described in Chapter 5. In this approach, you add code one piece at a time, testing new features in isolation as much as possible. When you add code to your ICF and ADF, you can use the following instructions to update the instance:

1.	Open a Notification Services Command Prompt and navigate to the Scripts directory of the new instance using the following command: cd /d C:\SQL-NS\NewInstances\MyNewInstance\Scripts
2.	Run disable.cmd to disable the instance.
3.	Stop the new instance's SQL-NS Windows service using the following command: net stop NS$MyNewInstance
4.	Run update.cmd to compile the changes to the source files and update the instance.
5.	Run enable.cmd to reenable the instance.
6.	Restart the instance using the following command: net start NS$MyNewInstance

After performing these instructions, the new code should be in effect, and you can begin testing it.