Using the URT Configuration System

Getting Started Guide
Application Server/Universal Runtime
Microsoft Confidential

Author	Van Van
Area	Configuration System
SubArea	Getting Started Guide
Program Management	Markus Horstmann
Development	Robert Craig
Test	Michael Fanning
Reviewers	Robert Craig
Current Version	0.9
Version History	0.9: 12/07/99 : Updated installation instruction for managed config. 0.8: 11/15/99 : Added instruction to install drops of managed configuration system. 0.7: 11/09/99 : Added reg keys required by system event logging 0.6: 10/18/99 : Changed setup contact to URTSetup. Clarified internal vs. external files. Cosmetic edits - MarkusH 0.5: 10/15/99 : Added check-in procedure - MarkusH 0.4: 10/13/99 : Added examples on how to extend collections - MarkusH 0.3 : 10/5/99 : Updated BVT instruction - MarkusH 0.2 : 9/13/99 : incorporated RCraig's comments - VanVan 0.1 : 8/23/99 : file created - VanVan
Status	Initial Draft

Using the URT Configuration System.. 1

Overview.. 2

Manual Setup. 2

Testing the Install 3

Installing the managed configuration system.. 3

Reading Configuration Data. 4

Extending the Schema. 4

Example 1: Adding a column to the Fusion “BindingPolicy” table. 5

Example 2: Adding a column to the Ducttape “Application” table. 6

Example 3: Adding a new collection. 7

Making the schema part of the shipping product 7

Writing Plugins. 8

Running BVTs. 8

Check-in procedure. 8

File list for Setup. 9

Files. 9

Registry Keys. 10

Overview

As more and more groups begin using the URT Configuration System (URTConfig for short), there needs to be a definitive guide which takes someone who has little to no knowledge about the URTConfig from installing it to actually using it. This document does NOT touch on the in depth technical aspects of the URTConfig. You will need to read the technical specification for that. Instead, this document solely focuses on the user perspective of actually using the URTConfig either in their code or testing.

Manual Setup

Currently, we do not have a setup program which does everything for the user. This may or may not appear depending on our delivery vehicle. In the meantime, you can follow these simple steps to setup the URT Config system either for testing or coding against.

Go to the drop location: \\urtdist\builds and pick up the latest build of the Config. The full path is

\\urtdist\builds\{buildnum}\{platform}{buildtype}\Config

For example,

\\urtdist\builds\0823\x86fre\Config

Copy everything at this location into a directory of your choice that is NOT on your path. For example, do not copy it into your %windir%\system32 directory. Instead, create a directory (or use an existing one) like C:\Config.

NOTE: If you plan on running our current BVTs on this install, you will need to install in the %windir%\XSPDT directory. This will change in the future, but for now, it is hard coded in our BVT TEST ONLY.

2. Go to the test drop location: \\urtdist\testdrop and pick up the latest build of the test tools that you will also need. The full path is

\\urtdist\testdrop\{buildnum}\{platform}{buildtype}\Config

For example,

\\urtdist\testdrop\0823\x86fre\Config

Copy everything at this location into the exact same directory as the one you used/created in the previous step. Although these files are not necessary, they are really helpful in any debugging and testing scenarios.

3. Open up a command prompt and go into the directory you copied all the files into (e.g. C:\Config). Run the following command:

catutil /product=urt /dll=C:\Config\Catalog.dll

A few things to note here. Although the product name can be anything, you will need to be consistent with the name. If you choose something, you will need to specify the exact same name when calling the APIs to retrieve config info. The value of /dll needs to be the full path to Catalog.dll (wherever you copied it). In this example, we are using C:\Config\Catalog.dll.

NOTE: All this does is creates the registry keys described below.

Once you've done all this, the Config system is installed and ready to go.

Testing the Install

To test and make sure you have everything installed correctly and running, you can do a few things (you don't need to do all of the following, just one is fine):

Run the current BVT tests.
Use STest to check your install. Use the command prompt and navigate to the directory where you installed all the files. Run the following command:

stest /view /d:meta /t:tablemeta

You should see 30 some table entries. This is an indication that things are working. All this does is displays the table meta information that is in the Config system.

You can also use stest to view any information known to the configuration system. Please refer to stest itself for the syntax and parameters.

Installing the managed configuration system

To install (sorry no integrated setup yet):

· Install the latest COM+ 2.0 build from file:\\urtdist\builds. M10 builds have build # < 1206, i.e. file:\\urtdist\builds\1204\x86fre\setup.exe.

· Copy the latest M11 config build from \\urtdist\builds to your config directory, typically %windir%\xspdt. M11 builds have build# >=1206, i.e. \\urtdist\builds\1206.5\x86fre\config.

· copy mngdIST.DLL to configuration.DLL (in your config directory).

· Re-Register the configuration system:

cd %windir%\xspdt

catutil /product=URT /dll=%windir%\xspdt\catalog.dll

To try it out:

· copy \\urtdist\TestDrop\<M11 build#>\x86FRE\Config\machine.cfg to your config directory. Make sure to save your machine.cfg file if you modified and care about it!

· In machine.cfg: Make sure the HomeDirectory for Site "312" (the site last in the file) points to the config directory using an actual path, e.g. c:\winnt\xspdt, NOT %systemroot%\xspdt.

· Download test binaries from http://appcenter/config/testfiles: mwiring.xml, config.cfg, testmerger.exe, system.handler.dll. (right-click "Save Target As...") to your config directory, e.g. %windir%\xspdt. Make sure config.cfg gets downloaded correctly (Select "All Files" to avoid the .xml file extension being automatically appended to config.cfg by IE).

· Create sub directories foo and foo\bar under %windir%\xspdt

· copy config.cfg and catalog.xms into both foo\ and foo\bar.

· Run "testmerger.exe URLPermissions" or "testmerger.exe UserDatabase" or "testmerger.exe ScriptMaps2" (sources in $/catalog42/src/urt/handlers/testmerger.cool).

Reading Configuration Data

Once everything is in working order and has passed your tests, either BVT or otherwise, you can start using it within your code. In order to code to it, you will need to:

Include catalog.h
Include catmeta.h
Link with the static lib cat.lib

You can look at stest.cpp for some sample code.

TODO: We really need a small simple sample that shows how to easily read/write config information here.

Extending the Schema

Schema information is stored in catmeta.xml (see catmeta.xms for respective schema). Wiring information is expressed in catwire.xml (see catwire.xms for respective schema).

If you wish to change the schema (add your own property) and/or wiring information, you should modify catmeta.xml and/or catwire.xml appropriately. When you are done, run

catutil /validate filename

where filename is the .xml file you just modified. This will validate and make sure you didn't make any mistakes when you modified the file. Once it's been validated, then run

catutil /compile /dll=C:\Config\Catalog.dll

to "compile" your changes. No source code compilation actually occurs. This command:

generates an XML schema: catalog.xms
generates a C style header of constants: catmeta.h
modifies catalog.dll with the new schema information

Example 1: Adding a column to the Fusion “BindingPolicy” table

Open catmeta.xml, find the “BindingPolicy” table:

<TableMeta InternalName="BINDINGREDIRTABLE" PublicRowName="BindingRedir"

            SchemaGeneratorFlags="EMITXMLSCHEMA" PublicName="BindingPolicy">
      <ColumnMeta InternalName = "Name"                     Type="WSTR" MetaFlags="PRIMARYKEY"/>
      <ColumnMeta InternalName = "PK"                       Type="WSTR" MetaFlags="PRIMARYKEY"/>
      <ColumnMeta InternalName = "Version"                  Type="WSTR" MetaFlags="PRIMARYKEY"/>
      <ColumnMeta InternalName = "VersionNew"               Type="WSTR" />
      <ColumnMeta InternalName = "NoPublisherPolicy" Type="WSTR" />
</TableMeta>

Add the definition for the new column and save catmeta.xml:

<TableMeta InternalName="BINDINGREDIRTABLE" PublicRowName="BindingRedir"

3. In the catalog directory (i.e. c:\config), run “catutil /validate catmeta.xml”. Fix any errors reported.

4. In the catalog directory, run “catutil /compile /dll=c:\config\catalog.dll.

Example 2: Adding a column to the Ducttape “Application” table

Ducttape uses persistent caching. For this reason, there are two table definitions for each table: one for the “raw” data as stored in the configuration file, and another one for the persisted data as consumed by Ducttape:

<!—- Configuration file definition -->

<TableMeta InternalName="APPS_CFG" SchemaGeneratorFlags="EMITCLBBLOB">

<ColumnMeta InternalName="AppEnabled" Type="UI4" />

<QueryMeta InternalName="All" MetaFlags="ALL" />

</TableMeta>

<!—- Persisted table definition: the additional columns are computed by the cookdown logic -->

<TableMeta InternalName="APPS" SchemaGeneratorFlags="EMITCLBBLOB">

<ColumnMeta InternalName="SrcCFGFile" Type="WSTR" />

<ColumnMeta InternalName="AppURL" Type="WSTR" MetaFlags="PRIMARYKEY" />

<ColumnMeta InternalName="SiteID" Type="UI4" MetaFlags="PRIMARYKEY" />

<ColumnMeta InternalName="AppPoolID" Type="WSTR" />

<ColumnMeta InternalName="AppEnabled" Type="UI4" />

<QueryMeta InternalName="All" MetaFlags="ALL" />

</TableMeta>

The table for the configuration file usually has the name of the persisted table plus a “_CFG”, i.e. “APPS” and “APPS_CFG”.

In order to add a column, a new ColumnMeta entry with matching types has to be added to both table definitions (as illustrated in Example 1). If the new column requires no processing, but merely needs to be copied through to the persisted table, no further coding is needed.

Edit catmeta.xml:

<!—- Configuration file definition -->

<TableMeta InternalName="APPS_CFG" SchemaGeneratorFlags="EMITCLBBLOB">

<ColumnMeta InternalName="AppEnabled" Type="UI4" />

<ColumnMeta InternalName="MyNewColumn" Type="WSTR" />

<QueryMeta InternalName="All" MetaFlags="ALL" />

</TableMeta>

<!—- Persisted table definition: the additional columns are computed by the cookdown logic -->

<TableMeta InternalName="APPS" SchemaGeneratorFlags="EMITCLBBLOB">

<ColumnMeta InternalName="SrcCFGFile" Type="WSTR" />

<ColumnMeta InternalName="AppURL" Type="WSTR" MetaFlags="PRIMARYKEY" />

<ColumnMeta InternalName="SiteID" Type="UI4" MetaFlags="PRIMARYKEY" />

<ColumnMeta InternalName="AppPoolID" Type="WSTR" />

<ColumnMeta InternalName="AppEnabled" Type="UI4" />

<ColumnMeta InternalName="MyNewColumn" Type="WSTR" />

<QueryMeta InternalName="All" MetaFlags="ALL" />

</TableMeta>

Run “catutil /validate catmeta.xml”
Run “catutil /compile /dll=c:\config\catalog.dll”

Example 3: Adding a new collection

Simply add a new <TableMeta> elements to the appropriate <DatabaseMeta> section in catmeta.xml (copying and existing one and modifying it is usually the easiest).

Note: The DatabaseMeta determines which interceptors (i.e. read from XML, CompLib etc.) will be used to handle the new collection, so pick a Database that contains collections with similar semantics as the one you are adding[1].

Note: To add a collection to the persisted cache (cookdown), code changes are required in current drops!

Making the schema part of the shipping product

For the December release, schema changes need to be checked into the Config source tree (\\urtsrc\config $/catalog42/src/bin/core/catinproc/catmeta.xml).

Please follow the Config team check-in procedures!

Request access to the config sources via \\lab7\groupease. E-mail MarkusH for VSS write access.

Writing Plugins

TODO: Need to include info here on how to write plugins and perhaps even sample code.

Refer to the Native-code configuration system spec for details on interceptors, wiring etc.

Running BVTs

To run the current BVT tests, you need to

Install the Config system as indicated in the Setup section of this document, BUT you must install everything in the %windir%\XSPDT directory. Basically, you will need to follow the directions carefully and wherever appropriate, use %windir%\XSPDT as opposed to any arbitrary directory.

Create a local directory (i.e. c:\mybvt) to hold the BVT files
Start the BVT from the current directory, i.e.
    cd c:\mybvtdir /d
     \\astdrop\drop\x86\catalog\caturtbvt build_number [checked/free, default is checked]
    Example: caturtbvt 0927

WARNING!!! The BVT will copy all the necessary configuration files into both the current directory and the winnt\xspdt directory. So your files in the current directory and windows\xspdt will be replaced!!

NOTE FOR CHECKED BUILDS: You will need msvcrtd.dll in order to run the checked version of Testcookdown.exe. Make sure you copy this into the same directory as Testcookdown.exe (that is, %windir%\XSPDT). This dependency will be removed in future builds.

Check-in procedure

Get a code/schema read from a CatCore developer.
Perform a full “get” on the catalog42 source tree.
Apply your changes and build at least “checked”. Building “free” is optional but highly recommended if you make any code changes.
Run BVTs on at least the checked build.
Check in.
Send check-in mail to CatChk
Get a buddy build (optional).

Do not check in during the config build time (currently 7AM Mo-Fr), up-to-date build schedules on http://urt/build.asp.

Contact MarkusH / RCraig to obtain permission for check-in during lock down.

File list for Setup

This section details all the files/reg keys and other information about the Config system.

Files

Internal Core
`Catalog.dll` `catalog.xms`	This is the primary .dll which is built. The other file is the XML schema file needed by the catalog as well.
External Core
`MSXML.DLL` `SHLWAPI.DLL` `URLMON.DLL`	These files are external and built by the IE5 team. We are currently dependent on these file and are negotiating a redistribution .dll that we can ship with the product. This is still on-going and whether we will ultimately ship these or just be dependent on IE5 is still in debate and negotiations. For now, you must also copy these files in order for the Config system to work.
External Dependencies (that we don't ship)
`MSVCRT.DLL` `MSVCRTD.DLL`	We require MSVCRT.DLL in order to run the catalog, however, we don't ship this because it comes standard with all the OS' such as Win9x, WinNT4, and Win2K. The counterpart is a dependency we have in Checked builds only (MSVCRTD.DLL). This is not an issue as we will not be shipping Checked builds.
Managed Code
`MngdIST.dll`	If you are writing managed code and need managed code access, you will need this as well.
Debug Files
`Catalog.pdb`	For debugging purposes only
Schema Extension (internal only)
`catmeta.xml` `catmeta.xms` `catutil.exe` `catwire.xml`	These files are not necessary for the running of the Config system. However, if you ever need to change the schema information (like adding a property) or chaning the wiring information, you will need these XML files and the tool to recompile them.
Config SDK (Internal only)
`cat.lib` `catalog.h` `catmeta.h`	If you are writing code that uses the Config system, you will need to include the header files and link with the .libs.
Test Tools and Files (Internal only)
`App.XML` `AppPool.XML` `Global.XML` `stest.exe` `stest.pdb` `TestCookDown.exe` `TestCookDown.pdb` `VirtualSite.XML`	These are the test tools and their respective debugging files and sample test files used by the test tool only.

Registry Keys

Notice: this registry key may change without notice!

Use the GetMachineConfigDirectory APIs (mangaged & unmanaged) to obtain the config directory location. Link to cat.lib to access catalog.dll.

If you need to manually install catalog drops, use “catutil /product=URT” as described above.

With build 1019 the registry key/value structure has changed!

HKLM\Software\Microsoft\Catalog42

Within this key a sub key is defined for each “product” (as passed to the GetSimpleTableDispenser API in cat.lib).

Example: HKLM\Software\Microsoft\Catalog42\URT

Within this product key, two named values are defined:

Name: “Dll”. Value: full path to (including) catalog.dll. Example: “c:\config\catalog.dll”, in the future likely “%windir%\COMPlus\Bin”.

Name: “MachineConfigDirectory”. Value: full path to the directory that contains the machine configuration file (machine.cfg). Example: c:\config, in the future likely “%windir%\COMPlus\Config”.

With build 1108 the following additional registry keys/values are required:

HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application\COM+ Config

Within this key, add two values:

Name: “EventMessageFile”. Value: fully qualified path to catalog.dll

Name: “TypesSupported”. Value: 0x07 (DWORD)

HKLM\SYSTEM\CurrentControlSet\Services\EventLog\System\COM+ Config

Within this key, add two values:

Name: “EventMessageFile”. Value: fully qualified path to catalog.dll

Name: “TypesSupported”. Value: 0x07 (DWORD)

The following people (and only those) will be notified of changes to this registry key/structure (e-mail MarkusH to be added to this list):

· URT Setup

Previous registry structure (before build 1019):

HKLM\Software\Microsoft\Catalog42

Within this key, a new String value is necessary.

Name: URT
Value: full path to (including) Catalog.dll (e.g. C:\Config\Catalog.dll)

[1] Interceptor wiring happens via the default database wiring in catwire.xml; refer to the Native-code configuration system spec for details on interceptor wiring, including per-collection wiring.