Microsoft Windows NT Embedded 4.0: Defining a Component Using Component Designer

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Microsoft Corporation

September 2000

Applies to:
    Microsoft Windows NT Embedded 4.0

Summary:Using Component Designer, a companion tool to Target Designer, you can create a component definition file to define the components you add to the Target Designer system database. After creating your component definition file, you can import it into Target Designer and add the new components to an embedded operating system (OS) configuration. (13 printed pages)

Contents

Introduction
Using KDF Files
Defining the Component
Additional Information

Introduction

Using Component Designer, a companion tool to Target Designer, you can create a component definition file to define the components you add to the Target Designer system database.

A component definition file contains system instructions for the components, including their capabilities and dependencies. You can also configure capabilities and components by using information in your development system, such as your local registry or the Target Designer system database.

After creating your component definition file, you can import it into Target Designer and add the new components to an embedded operating system (OS) configuration.

Using KDF Files

A component definition file contains a .kdf extension. Although you can define a component in a .kdf file using a text editor, as described in Target Designer online Help, it is much simpler to define a component using the Microsoft Windows NT Embedded component authoring tool, Component Designer.

Prerequisites for Creating a Component Definition File

For every component that you want to include in the component definition file, you must identify the following:

• Component application files and their registry entries
• Required support files. Support files provide additional information for a component:
  • Target Designer extension (.tdx) files provide properties that work with the target system registry. All configurable components that you add to your configuration require these supporting files.
  • Performance counter (.ini) files provide information used by the performance counter, and must be in the format used by the LODCTR utility.

    Note   When you import a component definition file into Target Designer, support files and the .h files defined in performance counter files are also imported.

    Dependencies or conflicts with other components or capabilities

    After determining where you want to list the capabilities and components in the Target Designer All Nodes pane, you can create a new component definition file. When you open Component Designer, a new component definition file opens. If you are working in an existing component definition file and want to open a new one, use the following procedure.

    To create a new component definition file

    1. In Component Designer, on the File menu, click New.
    2. In the new window, on the File menu, click Save As.
    3. In the Look intext box, select the location for the new component definition file.
    4. In the File nametext box, enter the file name for the new component definition file, and then click Save.
    5. If the Choose a File Namedialog box appears, do the following:
       • Select a path for the file.
       • In the File nametext box, type a unique file name, and then click Save.
       • To save the file in Unicode format, select the Save as Unicodecheck box. A component definition file that has been saved in Unicode format is saved in that format thereafter.

         Setting Component Definition File Properties

         You must set component definition file properties so that Target Designer can identify pertinent information, such as the file name, designated platform, and operating system.

         The component definition file properties can be set in the Component Designer navigation pane. In the pane, right-click the component definition file name, and then click Properties. The following table shows the properties that can be set in the dialog that appears.

         Property	Description
         Component name	The unique name of your component definition file. After you import the component definition file into the Target Designer, this name is displayed in the All Nodes pane.
         Vendor	The company that creates the component definition file.
         Description	A description of the component definition file.
         Version (major and minor)	The vendor version.
         Release date	The creation date of the component definition file. Example: 12/30/1998
         Platform	The hardware platform type. Example: i386
         Operating system (OS)	The operating system type. Example: WINNT
         OS version	The version of the operating system. Example: 4.0
         Repository	The basic directory from which to install most files: %%WinNT%%for the Windows NT basic directory. %%Repository%%for the repository directory in Target Designer installation root directory. Note   Specify a repository path relative to the directory in which you put the component definition file.
         Language	The language for the target system.

         Defining the Component

         You must define the component, associated capability, support files and dependencies. You do this by selecting a section in the left pane of the Component Designer, and then entering information about the component and its relationship to other components, including conflicts and dependencies.

         Using the following table, click on the appropriate section, and then perform the procedure.

         Section	Description	Procedure
         Capability	Use this section to do the following: Identify capabilities in the Target Designer database (TDSD) under which to put the component. Add a capability to the TDSD for the component.	To add a capability In the Component Designer navigation pane, right-click the component definition file, and then click Add Capability. In the Capability Propertiesdialog box, enter the appropriate information for the following: Capability—Type the name of the capability. TD extension file—Browse for and select the Target Designer extension (.tdx) file associated with the capability. Or, leave the text box blank to use the same extension file as the parent capability. TD extension index—Target Designer .tdx file might contain one or more dialog boxes. Type the extension index that points to the correct dialog box in the extension file. Or, leave the text box blank to use the same extension file that the parent capability uses. Note   The first dialog box = extension index 0. In the Hierarchy pathlist box, select the node to contain the capability after you import the component definition file into Target Designer. Note   In the Hierarchy pathlist box, only bold nodes are available.
         Component Section	Use this section to do the following: Identify a component and its support files. Select the path in the Target Designer Database in which to put the component when you import it into Target Designer. Note   Support files might be Target Designer extension (.tdx) or performance counter (.ini) files.	To add a component If necessary, add the capability in which you want to put the component. In the Component Designer navigation pane, right-click the parent capability, and then click Add Component. In the Component Properties dialog box, enter the appropriate information for the following: Component—Type a unique name for the component. Description—Type the description of the component. TD extension file—Browse for and select the Target Designer extension (.tdx) file associated with the component. Or, leave the text box blank and use the same extension file that the parent capability uses. TD extension index—Target Designer .tdx file might contain one or more dialog boxes. Type the extension index that points to the correct dialog box in the extension file. Or, leave the text box blank to use the same extension file that the parent capability uses. Note   The first dialog box = extension index 0. Performance counter file—To use performance counters with this component, type the file name of the performance counter file, including the .ini extension. Note   The performance counter file must be in the format used by the LODCTR utility. When you import the component definition file into Target Designer, this file and .h files defined in it are also imported. You can add the performance counter file later by typing the appropriate file name, and then putting the file and .h files in the repository subdirectory for the component definition file. In the Hierarchy pathlist box, select the node to contain the component after you import the component definition file into Target Designer.
         Files Section	Use this section to identify source and target files to import along with the component definition file.	To add a file In the Component Designer navigation pane, expand the appropriate component. Under the expanded component, right-click Files, and then click Add File. In the File Propertiesdialog box, enter the appropriate information for the following: File name—The name of the file to be added. Size—The size of the file in bytes to be added. The size of the file affects the running count displayed on the status bar for the selected configuration or component. Source path—The location of the file. Type the path, or the relative path to repository path. When Target Designer builds the software, it searches this path for your file. Target path—The relative path to the directory in which Target Designer installs your target system. Note   The target system install directory is specified in the Target Designer Image menu/Settings. Target name—The file is saved to this name in the target path. Note   To use the same name as the source file, leave this empty.
         Registry Section	Use this section to enter registry values and data required for the component to perform properly on the target system.	You can add registry information manually or drag the information from the local registry. To add a key from the local registry In the Component Designer navigation pane, expand the appropriate component. Under the selected component, right-click Registry, and then click Drag from Local Registry. In the Local System Registry navigation pane, browse for the appropriate registry key to add. In the Local System Registry details pane, right-click the registry key or value, and then click Copy. In the Component Designer navigation pane, under the appropriate component, right-click Registry, and then click Paste. Note   You can drag-and-drop a registry key from the local registry to Component Designer. When you copy a registry key, all subkeys and values are included, and the links of the registry key are resolved. When you copy a registry value, the associated key is also copied. To add a registry hive In the Component Designer navigation pane, expand the appropriate component. Under the expanded component, right-click Registry, and then click Add Hive File. In the Add Hive dialog box, enter the appropriate following information for the hive: Key name—The absolute registry subkey path in which to put the registry hive. Hive file—The file name for the hive, including the .hiv extension. You can browse for this file. Note   When you import the component definition file into Target Designer, the hive file is added under the specified key in the Target Designer system database.
         Needs	Use this section to define dependencies between the following: Capabilities with other capabilities on which they depend. Components with other components on which they depend. Components with capabilities on which they depend. Capabilities with components on which they depend.	For your target system to work properly, you must define dependencies or conflicts that exist between capabilities and components. The correct procedure for defining dependencies and conflicts is determined by the location of the other component or capability: In the component definition file—Drag a component or capability from the Component Designer details pane to the appropriate node (Needs, Needed by, or Conflicts) in the navigation pane. In the database—In the navigation pane, under the appropriate component, right-click the appropriate dependency type node (Needs, Needed by, or Conflicts), and then click Drag from Database. From the Component Database window, drag the appropriate capability to the Component Designer navigation pane. Target Designer verifies that all dependencies are met and that no conflicts exist when you do the following: Add a component to your target system. Check dependencies on a target system that includes the added component.
         Needed by	Use this section to define dependencies between capabilities and components. Capabilities with other capabilities on which they depend. Components with other components on which they depend. Components with capabilities on which they depend. Capabilities with components on which they depend.	For your target system to work properly, you must define dependencies or conflicts that exist between capabilities and components. The correct procedure for defining dependencies and conflicts is determined by the location of the other component or capability: In the component definition file—Drag a component or capability from the Component Designer details pane to the appropriate node (Needs, Needed by, or Conflicts) in the navigation pane. In the database—In the navigation pane, under the appropriate component, right-click the appropriate dependency type node (Needs, Needed by, or Conflicts), and then click Drag from Database. From the Component Database window, drag the appropriate capability to the Component Designer navigation pane. Target Designer verifies that all dependencies are met and that no conflicts exist when you do the following: Add a component to your target system. Check dependencies on a target system that includes the added component.
         Conflicts	Use this section to define conflicts between the following: Capabilities and other capabilities Components and other components Components and capabilities Capabilities and components	For your target system to work properly, you must define dependencies or conflicts that exist between capabilities and components. The correct procedure for defining dependencies and conflicts is determined by the location of the other component or capability: In the component definition file—Drag a component or capability from the Component Designer details pane to the appropriate node (Needs, Needed by, or Conflicts) in the navigation pane. In the database—In the navigation pane, under the appropriate component, right-click the appropriate dependency type node (Needs, Needed by, or Conflicts), and then click Drag from Database. From the Component Database window, drag the appropriate capability to the Component Designer navigation pane. Target Designer verifies that all dependencies are met and that no conflicts exist when you do the following: Add a component to your target system. Check dependencies on a target system that includes the added component. To add comments to the component definition file In the Component Designer navigation pane, right-click your component definition file, and then click Comments. In the KDF comments list box, type additional comments to the component definition file. To save the component definition file, on the File menu, click Save. You are now ready to import the component definition file into Target Designer and add your component to a configuration. Additional Information The following tips may help you create components for Microsoft Windows NT Embedded 4.0. Use Sysdiff to Discover Necessary Files and Registry Keys Sysdiff is a Microsoft tool that creates a system difference package, applies a system difference package to a Windows NT installation, and can generate Windows NT installation information files (INFs) and $OEM$ distribution share points. To find the necessary files and registry keys to create components Install a clean version of retail Microsoft Windows NT 4.0 with Service Pack 5 (SP5) on a computer. "Clean" means no additional applications are installed, and you have not configured or changed the installation. Use SYSDIFF /SNAPto take a snapshot of the clean system. See the Sysdiff documentation for details. (See previously mentioned download instructions.) Install and configure your application on the computer. If the application or driver you are capturing with Sysdiff requires that you restart the computer or registers controls, allow this to occur before proceeding. This way, all necessary system changes will be reflected in the system difference package. Use SYSDIFF /DIFFon the computer to create the SYSDIFF package. Use SYSDIFF /DUMPon the package to inspect the package contents. Use Component Designer and the information you have gathered by using SYSDIFF /DUMPto build a Component Definition file (.KDF) for your component. Test Your Component on Windows NT Embedded 4.0 Minimal and Standard OS Configurations Many files and registry keys that are found in the Standard operating system (OS) component are not present in the Minimal OS component. By testing on a Minimal OS configuration, you can determine whether your component includes all the necessary files and registry keys. If your component does not work properly on a Minimal OS configuration, you can use various third-party file and registry monitoring tools while your component is running to determine the missing files and/or registry keys dependencies and add them to your component. Once you determine the missing resources, copy any missing files and registry keys directly to the running Windows NT Embedded 4.0 system and validate that your component works when they are present. Then, add them to the component and rebuild the configuration after you have identified all the missing files and registry keys. This approach verifies that the missing resources and your component work correctly, and saves time by not forcing you to rebuild and reinstall the embedded run-time image multiple times. The following are caveats to the "live copy" approach when you are working with registry keys: The CurrentControlSetkey is used on the live system, but this is mapped to the ControlSet001key in the KDF itself. Volatile registry key data (data that changes over the life of the application or system or is generated by the application or system at every run) should not be migrated to the embedded system. Some registry changes require that the application or driver be restarted, or that the system be restarted. Note that this is not a complete list, however, it illustrates some issues that must be considered when you use this technique, which may require the you rebuild the configuration with an updated KDF to completely and confidently test. Break Large Components into Smaller Pieces Large components, such as large applications or device drivers with many support files, are difficult to troubleshoot and update. Applications can be broken down into a core component and components for specific feature sets, while device drivers can be broken down into the actual driver and sets of support files. This approach allows for easier creation and troubleshooting of components, as well as flexibility in configuring systems. A logical breakdown of large components is largely determined by the nature of the application or driver to be put in the component. However, custom install options make this job easier. For device drivers and applications with customizable install options, install only the base application by using Sysdiff to capture the core components. Then, use the Windows NT 4.0 Add/Remove Programs application to add more features to the application, and use Sysdiff to capture the changes. For device drivers and applications without the ability to add features after the first install, multiple clean Windows NT 4.0 setups may be required to capture all possible installation scenarios. Help files should almost always be broken out into a separate component. Use Dependencies to Relate Components to Each Other When you break down a large component into smaller components, you lose the intrinsic relationships between the files and the registry keys in the component. You can use dependencies between the components to make sure, for example, that an application feature set is not added to a configuration without the application core files component being added as well. More Resources The Knowledge Base article, Q247824: INFO: Tips on How to Create Components for Microsoft Windows NT Embedded, contains information related to this article. © 2004 Microsoft Corporation. All rights reserved.