Editing Metabase Properties

  • Article

Applies To: Windows Server 2003, Windows Server 2003 with SP1

You can write metabase properties in MetaBase.xml as either schema-defined or custom properties. Writing schema-defined properties results in an efficient use of the IIS cache, which is where the in-memory metabase and schema are stored, because the attributes are inherited from the schema rather than rewritten for each instance of a property. Using custom properties is not recommended, because they might not show up in the UI and ADSI cannot access them after they have been created.

A schema-defined property is contained in the start tag of a key, and only the property name and value are defined. Attributes for a schema-defined property come from the metabase schema. In the following example, the EnableEditWhileRunning property is a schema-defined property with a value of zero, and it is written in the IIs_Computer key:

<IIs_Computer Location = "/LM"
   EnableEditWhileRunning = "0">

A custom property defines some or all of the attributes of a property. Unlike a schema-defined property, a custom property is written between the XML start tag and the end tag of a metabase key. Custom properties are easy to identify because the name of the element that contains the custom property is Custom. The name and attributes of a custom property are contained in an XML element named Custom.

At a minimum, the Name and ID attributes must be defined in a custom property. Other than the name of the property and the ID attribute, all remaining attributes for a custom property come from the schema, if they are undefined. You need to define the other attributes only when you want them to contain a different value than the schema-defined attribute values. In the following example, the Win32Error property is defined as a custom property with a value of zero, and it is written within the IIsFtpVirtualDir key.

<IIsFtpVirtualDir Location = "/LM/MSFTPSVC/1/ROOT">
   <Custom
      Name = "Win32Error"
      ID = "1099"
      Value = "0"
      Attributes = "INHERIT"/>
</IIsFtpVirtualDir>

Important

Each property that is defined in the schema (MBSchema.xml) has a unique ID attribute. When you define a known property as a custom property, you must specify the unique ID number for that property.

General Notes for Editing the Metabase

Keep the following points in mind when editing the metabase:

  • Properties with the SECURE attribute set are stored encrypted.

  • All text in MetaBase.xml is case sensitive.

  • The KeyType property contained in a node is used to determine the element or node type that is applied to the metabase path.

  • Nodes that do not contain a KeyType property are stored as the generic object IISConfigObject, which can contain any property, and any node can be contained within any other node.

  • Custom properties are allowed for any node type.

  • The IIS_Global node must not be edited.

  • A schema-defined property that violates the schema — for example, a misspelled property name — is logged and the property is ignored.

  • Custom properties require a metabase ID attribute.

  • The Multi-SZ attribute is replaced with the multistring value.

  • Flags contain bitmask identifiers.

  • The internal metabase implementation is Unicode. To support international and non-ASCII characters, the MetaBase.xml file is encoded in UTF-8 text format.

Changing Schema-Defined or Out-of-Schema Properties

You can use custom properties for the following purposes:

  • To use properties that are not schema-defined.

  • To use properties with different attribute values than what is available in the schema-defined properties.

When you write a property by using different attribute values than what is schema-defined, you must write the property as a custom property. Only the attributes that are different from the schema should be defined in MetaBase.xml.

The following example shows a schema-defined property:

AccessFlags = AccessWrite

The following example shows a custom property:

<Custom Name = "AccessFlags"
   ID = "6016"
   Type = "DWORD"
   Value = "1"
   UserType = "IIS_MD_UT_FILE"
   Attributes = "INHERIT"/>

Starting or Stopping IIS

When IIS is started or restarted, the metabase configuration that is stored in MetaBase.xml and the schema information that is stored in MBSchema.xml is read by the storage layer and then written to the in-memory metabase through ABOs, as shown in Figure 4.2.

If the MetaBase.xml file cannot be parsed when IIS is started or restarted, an error is sent to the event log and IIS does not start. The reasons that MetaBase.xml might not be parsed correctly include — but are not limited to — missing XML tags, misspelled property names, or corruption of the MetaBase.xml file. To determine the cause of failure, you can use the last history file to determine what has changed in the MetaBase.xml file. If the metabase cannot be parsed, you can also restore it to an earlier version by using the last manual backup or an automatically generated history file.

When IIS is stopped, it checks to determine whether the configuration node or the schema node have changed in the in-memory metabase since the last time the in-memory metabase was written to disk. The configuration node contains the metabase configuration, which is stored in the MetaBase.xml file. The schema node contains the metabase schema, which is stored in the MBSchema.xml file.

To minimize the amount of time that is required to stop IIS, the MetaBase.xml file is not written to disk if the configuration node in the in-memory metabase has not changed. If the configuration node in the in-memory metabase has changed since the last time the in-memory metabase was saved to disk, the MetaBase.xml file is overwritten with the contents of the configuration node, and a new history file is created. For more information about history files, see Naming the Metabase History Files.