Share via

About Editing the MetaBase.xml File While IIS Is Running

  • Article

With the release of IIS6.0, members of the Administrators group 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 the edit-while-running feature is enabled.

important Important You must be a member of the Administrators group on the local computer to perform the following procedure (or procedures), or you must have been delegated the appropriate authority. As a security best practice, log on to your computer using an account that is not in the Administrators group, and then use the Runas command to perform this procedure as an Administrator.

Edit-while-running depends on the metabase history feature to keep track of the changes that an administrator makes to the MetaBase.xml file. The metabase history feature is enabled by default.

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 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 noted 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 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.

The Edit-While-Running Process

Describes how edit-while-running works.

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, when an administrator attempts to save MetaBase.xml directly with an application such as Notepad, an error is generated and a file change notification does not occur.

Step 2: IIS looks in MetaBase.xml for the HistoryMajorVersionNumber value.

IIS reads the value of the HistoryMajorVersionNumber property in the MetaBase.xml file to determine the major version number.

Step 3: IIS looks in 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 step 4.

Step 4: Parse MetaBase.xml.

IIS parses the MetaBase.xml file to determine whether there are fatal Extensible Markup Language (XML) errors, such as missing XML end tags. If MetaBase.xml can be parsed successfully, IIS proceeds to step 5.

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/key exists within the in-memory metabase, IIS proceeds to step 7.

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

The changes are written to the in-memory metabase through ABOs.

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.
  • The in-memory metabase is write-locked by someone making a simultaneous change using Active Directory Service Interfaces (ADSI), ABO, or Windows Management Instrumentation (WMI) to the same metabase node or property.
  • The key in the in-memory metabase that changes were made to in the MetaBase.xml file does not exist. This could occur if an administrator deletes the key in the in-memory metabase, using a programmatic interface or IIS Manager, before the MetaBase.xml file is changed and saved to disk.

If a change is not written to the in-memory metabase for any of the reasons listed above, an error or warning is sent to the event log. 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 it 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.

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.

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.

You can protect against this by changing the access control list (ACL) of the metabase files or by having only one administrator for the computer. By default, only members of the Administrators group and the Local System account can access the metabase files. IIS uses the System account internally to change the metabase files, so the access control entry (ACE) must remain. For more information on ACLs, search for "access control" in Windows Help.

Related Topics