[This is preliminary documentation and subject to change]

# About Editing the MetaBase.xml File While IIS Is Running

With the release of IIS 6.0, IIS administrators can edit the metabase file directly while IIS is running and the changes are immediately applied to the in-memory metabase. This capability, known as edit-while-running, is possible because MetaBase.XML is a text file. Direct editing can be accomplished using common text tools like Microsoft Notepad when edit while running is enabled.

Edit-while-running is dependent on the The Metabase History Feature feature to keep track of the changes that an administrator makes to the MetaBase.XML file. The metabase history feature is enabled by default. For information about configuring metabase history, see Configuring the Metabase History Feature.

Note Edit-while-running is not enabled by default. For information about enabling edit-while-running, see Enabling Edit-While-Running.

## How Edit-While-Running Works

IIS uses the Windows file change notification to determine when the MetaBase.XML file has been saved. When IIS detects that the metabase file has been saved, a series of checks are made as illustrated by the steps in the following illustration. Several possible scenarios are presented, based on the results of the steps shown in the illustration, to demonstrate the behavior of edit-while-running.

Important The MBSchema.XML file cannot be edited directly by using the edit-while-running feature. Changes made to metabase schema must be made programmatically. For information about writing changes to metabase schema, see Extending the Metabase Schema.

The Edit-While-Running Process

Step 1: IIS receives a file change notification that MetaBase.XML has been saved.

IIS receives a file change notification from Windows when the metabase file is saved. If MetaBase.XML is write-locked or read-only when an administrator attempts to save MetaBase.XML directly with an application such as Notepad, an error will be generated and a file change notification will not occur.

Step 2: IIS looks within MetaBase.XML for the HistoryMajorVersionNumber value.

IIS reads the value of the HistoryMajorVersionNumber property within the MetaBase.XML file to determine the major version number.

Step 3: IIS looks within the history folder for the corresponding history file.

The corresponding history file is the file that is named with the highest minor version number with the same HistoryMajorVersionNumber value that was found in MetaBase.XML in step 2.

Was the corresponding history file found?

If the corresponding history file is found, IIS proceeds to the step 4. Edit-While-Running Scenario 7 illustrates what happens if the corresponding history file is not found in the history folder during this step.

Step 4: Parse MetaBase.XML.

IIS parses the MetaBase.XML file to determine whether there are fatal XML errors, such as missing XML end tags. If MetaBase.XML can be parsed successfully, IIS proceeds to step 5. Edit-While-Running Scenario 8 illustrates what happens if there are parse errors in MetaBase.XML during this step.

Step 5: Compare MetaBase.XML to the corresponding history file.

IIS compares the MetaBase.XML file to the corresponding history file of the same major version within the history folder. IIS determines the differences between the two files.

- If changes were not made to MetaBase.XML, a history file is not created and no further action is taken.
- If changes were made to MetaBase.XML, IIS proceeds to step 6.

Step 6: Check that the level exists in the in-memory metabase that changes were made to in MetaBase.XML.

IIS determines whether the level/node exists within the in-memory metabase that changes were made to in the MetaBase.XML file. If the level/node exists within the in-memory metabase, IIS proceeds to step 7. Edit-While-Running Scenario 5 illustrates what happens if the level does not exist within the in-memory metabase.

Step 7: Write the changes to the in-memory metabase through Admin Base Objects.

The changes are written to the in-memory metabase through Admin Base Objects.

Important A change that was made in MetaBase.XML might not be sent to the in-memory metabase for the following reasons:

- The change violates metabase schema-for example, a property name is misspelled.
- A node or property within the in-memory metabase is write-locked by someone making a simultaneous programmatic change to the same metabase node or property.

In either case, an error or warning is sent to the event log and the change might not be written to the in-memory metabase or to the history file. For more information about simultaneous updates, see Simultaneous Updates below.

Step 8: IIS creates a new history file that contains the contents of the corresponding history file and the changes that were written to the in-memory metabase in step 7.

A history file is created in the history folder. This new file includes the combination of contents of the corresponding history file plus the changes that were written to the in-memory metabase in step 7. The new history file is named with the major version number that was found within the MetaBase.XML file (the value of the HistoryMajorVersionNumber property that was determined in step 2) and the next highest minor version number. IIS looks within the history folder to find the highest minor version number that was used for the same major version number, and uses the next highest minor version number to name the new history file. This naming convention permits succeeding edits to the same major version of the file to work correctly as outlined in Edit-While-Running Scenario 1 and Edit-While-Running Scenario 3.

### Simultaneous Updates

IIS supports simultaneous updates between programmatic interfaces such as ADSI and WMI. However, under some circumstances, errors can occur as described in step 7 above. The rule is that the last write always wins. Edit-While-Running Scenario 5 illustrates how IIS behaves when an administrator programmatically deletes a site within the in-memory metabase and another administrator attempts to save changes to the same site by editing the MetaBase.XML file directly.

IIS also supports simultaneous updates between the programmatic interfaces and one administrator directly editing the MetaBase.XML file. However, simultaneous writes to the same metabase node or property can result in an error condition.

Edit-While-Running Scenario 6 illustrates why edit-while-running does not support multiple administrators simultaneously editing the MetaBase.XML file directly.

phrase 1, phrase 2, phrase 3

© 1997-2001 Microsoft Corporation. All rights reserved.