[This is preliminary documentation and subject to change]

Edit-While-Running Scenario 1

This scenario illustrates how edit-while-running works under the following conditions:

• Changes are made to the MetaBase.XML file, and the MetaBase.XML file is saved.
• The MetaBase.XML file is not write-locked.
• MetaBase.XML is not read-only.
• The MetaBase.XML file is not open for edits (does not contain newer changes than the temporary file).

What you will learn:

• How the major and minor version numbers are incremented when MetaBase.XML is edited directly and saved.
• How the major and minor version numbers are used to name files in the history folder.
• How IIS determines the changes that were made to MetaBase.XML and writes the changes to the in-memory metabase through Admin Base Objects.

Step 1:
For simplicity, this scenario starts with a clean install of IIS. When IIS is installed, a copy of MetaBase.XML is written to the history folder. The HistoryMajorVersionNumber value is not necessarily numbered starting with 1. The major version number could be a higher number, but the minor version number will always be zero whenever a history file is created as the result of the in-memory metabase being written to disk.

Step 2:
Using Notepad, open MetaBase.XML, edit the value of C to C=4, and save but do not close the MetaBase.XML file.

When MetaBase.XML is edited and saved, the following happens:

1. IIS receives a file change notification that the MetaBase.XML file has been saved.
2. IIS looks within the MetaBase.XML file for the value of HistoryMajorVersionNumber.
3. IIS looks within the history folder for the corresponding history file. The corresponding history file is the file with the same HistoryMajorVersionNumber value that was found in step 2 and that has the highest minor version number.
4. IIS verifies that the MetaBase.XML file can be parsed and is free of schema errors.
5. IIS compares the MetaBase.XML file to the corresponding history file to determine whether changes were made.

   Note    If the MetaBase.XML file was saved with no changes made, a history file is not created and no further action is taken.

6. IIS verifies that the metabase level exists in the in-memory metabase that the changes were made to.
7. The changes are written to the in-memory metabase through Admin Base Objects (ABO).
8. IIS creates a new file in the history folder that contains the contents of the corresponding history file and the changes that were written to the in-memory metabase. The file is named using the HistoryMajorVersionNumber value that was determined in step 2 and with the next available minor version number. The minor version number is calculated by incrementing the minor version number of the corresponding history file by 1.

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.
• The in-memory metabase is write-locked by someone making a programmatic change to the same metabase node or property, which prevents the changes from being written to the in-memory metabase

In this case, an error or warning will be sent to the event log and the change will not be written to the history file.

For more information about how the major and minor version numbers are used to create the name of the history file, see Naming the Metabase History Files.

Step 3:
Using Notepad to edit the MetaBase.XML file, change the value of C to C=5 and then save and close the file.

When MetaBase.XML is edited and saved, the following happens:

1. IIS receives a file change notification that the MetaBase.XML file has been saved.
2. IIS looks within the MetaBase.XML file for the value of HistoryMajorVersionNumber.
3. IIS looks within the history folder for the corresponding history file. The corresponding history file is the file with the same HistoryMajorVersionNumber value as was found in step 2, with the highest minor version number.
4. IIS verifies that the MetaBase.XML file can be parsed and is free of schema errors.
5. IIS compares the MetaBase.XML file against the corresponding history file to determine whether changes were made.

   Note    If the MetaBase.XML file was saved with no changes made, a history file is not created and no further action is taken.

6. IIS verifies that the metabase level exists in the in-memory metabase that the changes were made to.
7. The changes are written to the in-memory metabase through Admin Base Objects.
8. IIS creates a new file in the history folder that contains the contents of the corresponding history file and the changes that were written to the in-memory metabase. The file is named using the HistoryMajorVersionNumber value that was determined in step 2 and with the next available minor version number. The minor version number is calculated by incrementing the minor version number of the corresponding history file by 1.

Note    The HistoryMajorVersionNumber value that is written within the MetaBase.XML file is still 1. The next step in this scenario illustrates how HistoryMajorVersionNumber is incremented.

Step 4:
The in-memory metabase is written to disk.

When the in-memory metabase is changed and saved, the following happens:

1. IIS performs a series of verifications as detailed in Writing the Metabase to Disk.
2. IIS verifies that there are changes pending in the in-memory metabase.
3. IIS locks the in-memory metabase to prevent writes.
4. IIS determines the major version number.
5. IIS creates a temporary file containing the in-memory metabase configuration.
6. IIS unlocks the in-memory metabase to allow writes.
7. IIS copies the temporary file to the history folder and renames the file with the major and minor version numbers. The minor version number is reset to zero.
8. IIS verifies that MetaBase.XML is not write-locked. <Passed verification.>
9. IIS verifies that MetaBase.XML is not read-only. <Passed verification.>
10. IIS verifies that MetaBase.XML is not newer than the temporary file. <Passed verification.>
11. The temporary file is copied over MetaBase.XML, and the temporary file is deleted.
12. The oldest history file pairs are deleted.

Note    When a write-to-disk event occurs, the changes are not pushed from the history folder back into the in-memory metabase.

Step 5:
Using Notepad to edit the MetaBase.XML file, change the value of C to C=3 and then save and close the MetaBase.XML file.

1. IIS receives a file change notification that the MetaBase.XML file has been saved.
2. IIS looks within the MetaBase.XML file for the HistoryMajorVersionNumber value.
3. IIS looks within the history folder for the corresponding history file. The corresponding history file is the file with the same HistoryMajorVersionNumber value as was found in step 2, with the highest minor version number.
4. IIS verifies that the MetaBase.XML file can be parsed and is free of schema errors.
5. IIS compares the MetaBase.XML file against the corresponding history file to determine whether changes were made.

   Note    If the MetaBase.XML file was saved with no changes made, a history file is not created and no further action is taken.

6. IIS verifies that the metabase level exists in the in-memory metabase that the changes were made to.
7. The changes are written to the in-memory metabase through Admin Base Objects.
8. IIS creates a new file in the history folder that contains the contents of the corresponding history file and the changes that were written to the in-memory metabase. The file is named using the HistoryMajorVersionNumber value that was determined in step 2 and with the next available minor version number. The minor version number is calculated by incrementing the minor version number of the corresponding history file by 1.

© 1997-2001 Microsoft Corporation. All rights reserved.