Share via

Schema Documentation Program for Servers Running Windows 2000 or Windows  Server 2003 

  • Article

 

Microsoft Corporation

July 2002

Applies to:
    Microsoft® Windows® 2000
    Microsoft Windows Server 2003
    Microsoft Active Directory®

Summary: Learn how to install and run the Schema Documentation program for Windows 2000 Server or Windows Server 2003. (12 printed pages)

Download schemadocfile.exe.

Contents

Introduction
Files Extracted from Schemadocfile.exe
Registering the Schema Documentation Program
Running the Schema Documentation Program
The XML Output File
The XML Style Sheet
Editing the XML Output File
Creating Custom Comments as Classes
Installing the Test Schema Extension

Introduction

The Schema Documentation program allows you to document extensions made to the Microsoft® Active Directory® directory service. After you add custom schema extensions to a domain controller, you can use this program to document the extended schema.

The Schema Documentation program searches a directory based on a specified prefix. For every class or attribute that matches the prefix, the program copies information about the class or attribute into an XML file.

All data entered into the Schema Documentation program, except for the directory path and password, is stored in a configuration file. The configuration file prevents having to enter the information multiple times.

For the program to be effective, you must have used a prefix to define the schema extensions. To register a schema prefix and OID, visit the Active Directory Naming Registration Web page.

This paper shows how to install and run the Schema Documentation program. If you would like to try the Schema Documentation program on a test server, you can use the LDIFDE utility to install the sample schema files included with this paper. For information about how to install the sample schema files, see Installing the Test Schema Extension later in this paper.

Files Extracted from Schemadocfile.exe

When you run the self-extracting executable file Schemadocfile.exe, the following files are extracted:

  • Comments.ldf
    A sample file in the LDAP Data Interchange Format (LDIF) used by the LDIFDE utility to automatically add custom comments to an XML output file

    Note   Import this file into a directory after importing the Schema.ldf file. This file demonstrates how comments for a schema can be defined and later merged by this program.

  • Schema.ldf
    A sample file in the LDAP Data Interchange Format (LDIF) used by the LDIFDE utility to add schema extensions to an Active Directory schema

  • Schemadoc.doc
    The file you are now reading

  • Schemadoc.exe
    The Schema Documentation program

  • Schemadoc.xsl
    The style sheet used by the Schema Documentation program to display the XML output file in a more readable format

  • Xmlschema.dll
    The file used by the Schema Documentation program to scan a directory for classes and attributes that match the specified prefix

    Note   Before the Schema Documentation program can run, this file must be registered. For information about how to register the Xmlschema.dll file, see Registering the Schema Documentation Program, later in this paper.

  • Xmlschema.xml
    A sample XML output file generated by the Schema Documentation program.

  • Xslschema.xml
    The same file as Xmlschema.xml, except that Xslschema.xml uses the Schemadoc.xsl style sheet

Registering the Schema Documentation Program

To run the Schema Documentation program, you must first register the Xmlschema.dll file with the Microsoft Windows® operating system:

To register the Xmlschema.dll file

  1. Copy Xmlschema.dll to C:\Windows\System32.

  2. At a command prompt, go to C:\Windows\System32, and then type regsvr32 xmlschema.dll.

    The RegSvr32 message box appears with the following message:

         DLLRegisterServer in xmlschema.dll succeeded.

After you register the Xmlschema.dll file, you can run the Schema Documentation program.

Running the Schema Documentation Program

After registering the Xmlschema.dll file with the operating system, you can run the Schema Documentation program using the following procedure.

To run the Schema Documentation program

  1. At a command prompt, go to the folder that contains the Schemadoc.exe file, and then type schemadoc.exe. The Schema Documentation Program dialog box appears.

    Figure 1. The Schema Documentation Program dialog box

  2. Type the appropriate information in the text boxes.

    The following list describes the information to type in the text boxes:

    Directory path

    • The ADsPath to the schema for the directory; for example:

      LDAP://CN=Schema,CN=Configuration,DC=myComp,DC=com

    Naming prefix

    • The prefix that should appear at the beginning of each class and attribute name that has been extended in the schema. The prefix should be without dashes. If you have not used a specific prefix, then enter the name of the class or attribute. Entering the name of a class or attribute may result in an incomplete results file because the program will select an object that begins with the text in the Naming prefix text box.

    Output file

    • The path and file name of the XML output file.

      Note   The Schema Documentation program overwrites any existing files with the same file name, so if you want to keep earlier output files, remember to copy the file or change the file name before successive executions of the program.

    User name

    • The login ID for the Active Directory being documented. The user name can be the user ID for the directory or for the distinguished name. Here are a couple examples:

      administrator

      CN=administrator,CN=users,DC=mycomp,DC=com

      If this text box is left blank, the Schema Documentation program binds to the directory anonymously.

    Password

    • The password used to log into the Active Directory domain. This text box can be left blank.

    Domain

    • The domain used to authenticate the user. The text entered in this text box will be appended to the user name. For example, if the user name is administrator and the domain is mycomp, the system will use mycomp\administrator to perform the authentication.

    When you have finished, click Next. The Vendor Information dialog box appears.

    Figure 2. The Vendor Information dialog box

  3. Type the information about your company. This information is added to the output file and will be used by people who want to contact you with questions about the schema extensions.

    When you have finished, click Next. The Product Information dialog box appears.

    Figure 3. The Product Information dialog box

  4. Type the information about the product that the schema extensions represent. This information is added to the output file and will be used by people who want to understand the purpose of the schema extensions.

    Note   If the Description text box is too small, you can modify the Description text in the generated output file.

    When you have finished, click Execute.

    The output of the Schema Documentation program is copied into the file specified in the Output file text box of the Schema Documentation Program dialog box. The output file then appears in a browser window. The output file is in XML format.

The XML Output File

The output file of the Schema Documentation program is divided into the following sections:

  • Vendor
    The vendor section contains, as comments, the information you entered in the Vendor Information dialog box of the Schema Documentation program.
  • Product
    The product section contains, as comments, the information you entered in the Product Information dialog box of the Schema Documentation program.
  • Class
    The class sections contain all system and nonsystem attributes for each class in the directory that matches the prefix. The Xmlschema.dll file reads the important properties for each class in the directory that matches the prefix and then formats the data and adds it to the output file. The class sections contain any comment information retrieved from the directory for each class that matches the prefix. The vendor is to supply this information. Classes are listed by LDAP Display Name.
  • Attribute
    The attribute sections contain all class attributes that match the naming prefix specified in the Schema Documentation Program dialog box; other attributes that belong to the documented classes are ignored. The Xmlschema.dll file reads the important properties for each attribute in the directory and then formats the data and adds it to the output file. The attribute sections contain any comment information retrieved from the directory for each attribute. The vendor is to supply this information. Attributes are listed by LDAP Display Name.

The sample XML output file Xmlschema.xml shows how text entered in the text boxes of the Schema Documentation program will appear in the output file.

Comment Descriptions

The XML output file may contain comments that contain the text, Fill in. Replace this text with the appropriate information.

Here are descriptions of the comments:

  • comment-containedIn
    The classes that use the attribute.
  • comment-sizeInBytes
    The average number of bytes used by the attribute. This may also indicate a set of enumeration values.
  • comment-updateFrequency
    For a class, how often the class is created and deleted. For an attribute, how often the attribute is changed.
  • comment-updatePrivilege
    The privileges required to make changes to this class or attribute.
  • comment-usage
    How this class or attribute is to be used.
  • comment-VendorName
    The company name of the vendor.
  • comment-VendorPrefix
    The prefix used by the vendor to identify the schema extensions.
  • comment-VendorAddress
    The street address of the vendor.
  • comment-VendorCity
    The city for the address of the vendor.
  • comment-VendorStateOrProvince
    The state or province for the address of the vendor.
  • comment-VendorCountry
    The country for the address of the vendor.
  • comment-VendorPostalCode
    The postal code for the address of the vendor.
  • comment-VendorTelephone
    The telephone number of the vendor.
  • comment-VendorEmail
    The e-mail address of the vendor.
  • comment-ProductName
    The name of the product.
  • comment-ProductDescription
    A description of the product.
  • comment-VersionMajor
    The major version number of the product.
  • comment-VersionMinor
    The minor version number of the product.

The XML Style Sheet

You can use the XML style sheet file, Schemadoc.xsl, to display the XML output file in a more readable format.

To view the output file with the XML style sheet

  1. Copy the file Schemadoc.xsl to the directory that contains the XML output file.

  2. Open the XML output file in a text editor such as Microsoft Notepad, and type the following text as the first line of the output file:

    <?xml-stylesheet href="schemadoc.xsl" type="text/xsl"?>

  3. Save the output file, and close the text editor.

  4. Open the output file in a browser.

Editing the XML Output File

You can provide more information about your schema extension by manually adding custom comments to the XML output file.

When you edit the XML output file, be careful to use only supported characters. The XML parser does not support the ampersand (&), less than (<), and greater than (>) characters.

Before distributing the XML output file, be sure the file displays correctly in a browser window.

After you manually add custom comments to the XML output file, you may want to save the edited version under a new name for use with later output files.

Note   Unless you change the output file name in the Schema Documentation Program dialog box, the Schema Documentation program overwrites the file each time you run the program.

Creating Custom Comments as Classes

Custom comments can be automatically added to the XML output file each time you run the Schema Documentation program. This is accomplished by adding custom comments to the Active Directory schema as classes. To add comments to the Active Directory schema as classes, create a Comments.ldf file, and then edit the Comments.ldf file as follows:

To create a comment as an Active Directory class

  1. Create a Comments.ldf file using an ASCII editor, such as Microsoft Notepad.

  2. In the Comments.ldf file, create a schema container (where X is the name of the domain), and then run the schemaUpdateNow operational attribute:

    dn: CN=Schema,DC=X

    changetype: add

    objectClass: container

    dn:

    changetype: modify

    add: schemaUpdateNow

    schemaUpdateNow: 1

    -

  3. Create a comment as a storage class using the attributes in the following table. You add these attributes to the Comments.ldf to store various comment elements.

    Table 1. Attributes used to store comments

    Attribute Type of comment
    adminDescription The description displayed on administrator screens.
    adminDisplayName The name displayed on administrator screens.
    description The description displayed for an object. The system treats this value as a single value.
    displayName The name displayed in the address book for a particular user. This is usually a combination of the user's first name, middle initial, and last name.
    DisplayNamePrintable The name displayed in the address book for a particular user. This is usually a combination of the user's first name, middle initial, and last name.

    Except for CN=Configuration, the DN of the class used for the comment in Comments.ldf must be identical to the DN of the class the comment is being added to (see Schema.ldf). Do not use CN=Configuration because you are not creating a configuration container.

    Here is an example of a comment created as a storage class:

    dn: CN=ms-test-Car-License,CN=Schema,DC=X

    changetype: add

    adminDescription: 19 bytes.

    adminDisplayName: AD Users and Computers, ADSIEdit

    description: The license plate number for a car.

    displayName: When the record is created or the license number changes.

    displayNamePrintable: Anyone with the ability to update a user object.

    instanceType: 4

    objectClass: storage

    Note   Replace DC=X with DC=domain_name.

  4. After creating all comments as storage classes, be sure to run the schemaUpdateNow operational attribute as follows:

    dn:

    changetype: modify

    add: schemaUpdateNow

    schemaUpdateNow: 1

    -

  5. Use the LDIFDE utility to add the Comments.ldf file to the Active Directory schema as directed in Installing the Test Schema Extension, later in this paper.

The Schema Documentation program looks for a schema container named schema under the root domain. If you have added custom comments as classes, this container will have objects of the storage class, where the common name (CN) of each object is the same CN as its associated schema object. This permits the Schema Documentation program to recognize that a custom comment has been added for the schema object that uses that CN. The Schema Documentation program can then associate the custom comment to its class and add that data to the XML output file. For example, assume a schema object has the following distinguished name:

cn=MyClass,cn=schema,cn=configuration,dc=myDomain

When you create a storage object with the same CN in the schema container in the domain partition, the Schema Documentation program will then read the custom comment information contained as attributes of the storage object. This storage object would have the following distinguished name:

cn=MyClass,cn=schema,dc=myDomain

Installing the Test Schema Extension

Included in the self-extracting executable file Schemadocfile.exe are the following two files:

  • Comments.ldf
    A file in the LDAP Data Interchange Format (LDIF) used by the LDIFDE utility to add comments to a schema.

    Note   Add this file to a schema after adding the Schema.ldf file.

  • Schema.ldf
    The file in the LDAP Data Interchange Format (LDIF) used by the LDIFDE utility to add a predefined schema to Active Directory.

You can extend a schema with these files by using the LDIFDE utility and then view the changes using the Schema Documentation program. For more information about using the LDIFDE utility, see "Methods for Extending the Schema" in the Windows 2000 Server Resource Kit.

The following procedure assumes you have a domain controller called Fabrikam.com and a computer called main. You will first add the schema extensions followed by the comments file.

Be sure to only install these in a test forest. To clean out a schema and start over, you can demote all of the DCs in your test forest and promote them again with the DCPromo command. Be sure to save any important data in your directory before doing this.

To add the test schema extensions

  1. At a command prompt go to the subdirectory that contains the files Schema.ldf and Comments.ldf.

  2. At the command prompt, type the following LDIFDE command to install the test schema extension:

    ldifde –i –f schema.ldf –c DC=X "dc=main,dc=fabrikam,dc=com"

    The following text appears at the command prompt:

    Connecting to "main.fabrikam.com"
Logging in as current user using SSPI
Importing directory from file "schema.ldf"
Loading entries . . . . .
7 entries modified successfully.

  3. At the command prompt, type the following LDIFDE command to install the comments file:

    ldifde –i –f –c comments.ldf DC=X "dc=main,dc=fabrikam,dc=com"

    The following text appears at the command prompt:

    Connecting to "main.fabrikam.com"
Logging in as current user using SSPI
Importing directory from file "comments.ldf"
Loading entries . . . . .
8 entries modified successfully.

To see the results of adding the schema extension, run the Schema Documentation program with a naming prefix of testschema.