Appendix A. Best Practices
Important The guidelines outlined in this appendix are not required to comply with the Application Specification for Windows 2000, but are strongly encouraged to provide a better user experience.
A-1 Do not require a reboot for installation of your application on Windows 2000
A-2 Use SHGetFolderPath to determine special folder paths
A-3 Test your application under Terminal Services
A-4 Globalization
A-5 Localizability
A-6 Use 64-bit compatible data types
A-7 Additional Considerations for Cluster Service
A-8 Windows Management Instrumentation
A-9 Provide MMC snap-in for management tools
A-10 Expose a COM-based scripting model
A-11 Use COM+ for Distributed Applications
A-12 Run without NetBIOS in Windows 2000-only environment
A-1. Do Not Require A Reboot for Installation of Your Application on Windows 2000
Installation of your application should not require a reboot when you install it onto a freshly installed Windows 2000 system with no applications running, unless you are deploying any of the following as part of your install:
Operating system update package, such as service pack
System-level drivers, such as 3rd-party video drivers, disk drivers, and administrative-level privileged services.
Generally, a reboot on Windows 2000 should not be necessary, even if applications are running. In the past a typical reason applications would reboot was because they were replacing a file that was in use at the time. However, on Windows 2000, these situations are greatly reduced by Windows File Protection (WFP).
WFP protects essential system files, so applications should not attempt to replace them. These files will be updated only via an operating system update package, instead of in a piecemeal fashion by individual applications.
In addition, applications that use the Windows Installer will be less likely to need a reboot. Windows Installer service will automatically check to see if other applications or service processes are using files that it is attempting to update. In these cases, Windows installer will prompt the user to shutdown the applications that are using those files. If the user does this, the application can install without a reboot. If the user does not shut down those applications, Windows Installer will prompt for a reboot.
Note Based on strong customer feedback, we recommend that you
DO NOT REQUIRE A REBOOT UNLESS IT IS ABSOLUTELY NECESSARY.
A-2. Use SHGetFolderPath To Determine Special Folder Paths
Whenever you access any of the special folders in the following list, your application should use the Win32 APIs to dynamically obtain the proper language-specific folder names. The preferred way to do this is using the SHGetFolderPath API with the appropriate CSIDL constant. This function behaves consistently across Windows 95, Windows 98, Windows NT 4.0, and Windows 2000. This API is redistributable via the SHFOLDER.DLL. Software vendors are encouraged to redistribute this component as much as possible to enable this support on Windows operating systems prior to Windows 2000. Windows 2000 includes this DLL as a protected system file and, as such, this DLL cannot be replaced on Windows 2000 or greater.
Note To ensure your application can run on Windows 9x, Windows NT 4.0 and Windows 2000, always link to the SHGetFolderPath implementation in SHFOLDER.DLL. Windows 2000 natively implements SHGetFolderPath in SHELL32.DLL, but other versions of Windows do not include SHGetFolderPath in SHELL32.DLL.
| Standard Folder | CSIDL Constant Name |
| Alternate Startup ([user], DBCS) | CSIDL_ALTSTARTUP |
| Alternate Startup folder (All Users profile, DBCS) | CSIDL_COMMON_ALTSTARTUP |
| Application Data ([user] profile) | CSIDL_APPDATA |
| Application Data (All Users Profile) | CSIDL_COMMON_APPDATA |
| Control Panel virtual folder | CSIDL_CONTROLS |
| Cookies folder | CSIDL_COOKIES |
| Desktop (namespace root) | CSIDL_DESKTOP |
| Desktop folder ([user] profile) | CSIDL_DESKTOPDIRECTORY |
| Desktop folder (All Users profile) | CSIDL_COMMON_DESKTOPDIRECTORY |
| Favorites folder ([user] profile) | CSIDL_FAVORITES |
| Favorites folder (All Users profile) | CSIDL_COMMON_FAVORITES |
| Fonts virtual folder | CSIDL_FONTS |
| History folder | CSIDL_HISTORY |
| Internet Cache folder | CSIDL_INTERNET_CACHE |
| Internet virtual folder | CSIDL_INTERNET |
| Local (non-roaming) data repository for apps | CSIDL_LOCAL_APPDATA |
| My Computer virtual folder | CSIDL_DRIVES |
| My Pictures folder | CSIDL_MYPICTURES |
| Network Neighborhood directory | CSIDL_NETHOOD |
| Network Neighborhood root | CSIDL_NETWORK |
| Personal folder ([user] profile) | CSIDL_PERSONAL |
| Printers virtual folder | CSIDL_PRINTERS |
| PrintHood folder ([user] profile) | CSIDL_PRINTHOOD |
| Program Files folder | CSIDL_PROGRAM_FILES |
| Program Files folder for x86 apps on Alpha systems | CSIDL_PROGRAM_FILESX86 |
| Programs folder (under Start menu in [user] profile) | CSIDL_PROGRAMS |
| Programs folder (under Start menu in All Users profile) | CSIDL_COMMON_PROGRAMS |
| Recent folder ([user] profile) | CSIDL_RECENT |
| Recycle Bin folder | CSIDL_BITBUCKET |
| SendTo folder ([user] profile) | CSIDL_SENDTO |
| Start menu ([user] profile) | CSIDL_STARTMENU |
| Start menu (All Users profile) | CSIDL_COMMON_STARTMENU |
| Startup folder ([user] profile) | CSIDL_STARTUP |
| Startup folder (All Users profile) | CSIDL_COMMON_STARTUP |
| System folder | CSIDL_SYSTEM |
| System folder for x86 applications on Alpha systems | CSIDL_SYSTEMx86 |
| Templates folder ([user] profile) | CSIDL_TEMPLATES |
| User's profile folder | CSIDL_PROFILE |
| Windows directory or SYSROOT | CSIDL_WINDOWS |
A-3. Test Your Application Under Terminal Services
Many enterprise customers use Terminal Services to provide Windows 2000 applications to an array of desktop and mobile clients. Applications running under terminal services run only on the server. The Terminal Services client performs no local processing of applications. This means that in a terminal services environment, multiple instances of the same application may be running on the same machine at the same time, serving different users.
Considerations for developers
Because multiple users are running your application at the same time, it's critical to store application and user data properly. For more information, see Chapter 4, "Data and Settings Management" in the Desktop Application Specification.
In a Terminal Services environment, multiple instances of your application will be running on the same machine. Your application's .EXE and .DLL files should be written so multiple users can simultaneously run your application on the same machine. Considerations include:
File locking-Ensure that files are not locked during use, as this could prevent multiple instances of the application, or processes under the application such as wizards, from running.
File permissions-Users may not have access to system files, and may not have the same permission levels as the administrator who installed the application.
File locations-Per user data and configuration files should be stored separately to avoid collisions and manage permissions. In particular, applications should store temporary information on a per user basis to avoid conflicts among users' information and preferences. You should do this by using the GetTempPath API rather than using a hard-coded path.
Terminal Services manages objects on a per-client basis for you. You only need to implement object management if you do not want the operating system to do this for you. If a specific object should be available to all instances of the application, register the .DLL or .EXE that creates the object with the command register filename /system, or change the application to prefix the case-sensitive string Global\ (in C string form "Global\\") to the name of the object when it is created.
Pretesting guidelines
Set up a Windows 2000 Server computer as a Terminal Services Host and configure it to allow both administrator and non-administrator access.
Install the application on this machine logged on as an Administrator.
- The application should be installed in Terminal Services' Install mode. Use the command line "change user /install" or use Add/Remove Programs in the Control Panel. This is required so that Terminal Services can appropriately manage the registry for each user. An installation script may also be required to adjust file and registry settings for multiple users. See the white paper, "Using and Developing Applications Compatibility Scripts."
On a separate client machine, log on to the Terminal Services Host with normal (non-Power, non-Admin) User privileges.
Ensure that all shortcuts, files and folders are available to the user.
Launch each program in the application.
Run a full set of functionality tests on your application.
Create customized interface, file option and new default settings for the user.
Log on as a different user and make sure that the setting changes you made for the first user are not the new defaults for the new user.
Run a full set of functionality tests on your application simultaneously from two client computers as two different users.
Run a full set of functionality tests on your application simultaneously from two client computers with one (non-Power, non-Admin) User and one Administrator.
Diagnosing common problems
If the problem was encountered while logged on to a client as a user without administrative rights, try to reproduce the problem on the Terminal Services server console as the same user. If the problem goes away, this indicates that the application is using a system resource or configuration. The console session has all system processes, such as SMSS.exe, RPCSS.exe, SERVICES.exe, and LSASS.exe, and the Windows 2000 services associated with it.
If the problem is still present on the Terminal Services server console, log on to a client machine as an Administrator and repeat the test. If the error does not occur, the problem is probably a file permissions problem.
If the problem is still present, log on to the Terminal Services server console as an Administrator and repeat the test. If the error does not occur, the problem may be caused by incorrect permissions or the application is using a system resource or configuration.
References
Optimizing Applications for Windows 2000 Terminal Services and Windows NT Server 4.0, Terminal Services Edition
www.microsoft.com/windows2000/library/planning/terminal/tsappdev.asp
Using and Understanding APIs for Terminal Services
www.microsoft.com/ntserver/terminalserver/techdetails/prodarch/api.asp
Using and Developing Applications Compatibility Scripts
www.microsoft.com/ntserver/terminalserver/techdetails/prodarch/AppCompSc.asp
A-4. Globalization
Globalization is the practice of designing and implementing software that is not locale dependent, i.e., can accommodate any locale. In software design, a locale is defined as a set of user preferences associated with a user's language. A locale in Windows 2000 includes formats for date, time, currency and numbers; rules and tables for sorting and comparison; and tables of character classifications.
Other user preferences that a globalized application should accommodate include user-interface language, default font selection, language rules for use in spell checking and grammar, and input methods such as keyboard layouts and input method editors. See www.microsoft.com/globaldev/ for more details.
Guidelines for developing a globalized application include the following:
Use Unicode as your character encoding to represent text. If your application should also run on Windows 9x, consider a method for using Unicode on those platforms, as described in Microsoft Systems Journal articles in the November 1998 and April 1999 issues. These articles are available at:
www.microsoft.com/globaldev/articles/singleunicode.asp
www.microsoft.com/globaldev/articles/multilang.asp
If you cannot use Unicode, you will need to implement features such as DBCS enabling, BiDi enabling, codepage switching, and text tagging. Guidelines related to this functionality are available at www.microsoft.com/globaldev/.
Consider using a multilingual user interface-launch the application in the default user interface language, and offer the option to change to other languages.
Use the Win32 API national language support (NLS) functions to handle locale sensitive data.
Watch for Windows messages that indicate changes in the input language, and use that information for spell checking, font selection, etc.
Use the Script APIs (Uniscribe) to layout formatted text on a page. This will allow your application to display multilingual text and complex scripts such as Arabic, Hebrew, Hindi, Tamil, and Thai.
Test your application on in the following scenarios:
Where the system locale, the user locale, the input locale and the UI language each have different values and are all different from the localization language of the application
Where the system locale is not English (United States) and not the same as the application localization.
Where the user locale is new in Windows 2000 (e.g., Hindi)
Where the UI language is one of the right-to-left languages such as Arabic.
For a client/server application, where the client and server each have different locales
By using Regional Settings to customize the user locale (the more unusual the better for testing)
A-5. Localizability
In contrast to globalization, localization is the process of modifying an application so that its user interface is in the language of the user. Well designed software can be localized to any of the languages supported by Windows 2000 without changes to the source code, i.e., without recompilation. In addition to the guidelines for globalization mentioned above, those for localizability include the following:
Isolate all user interface elements from the program source code. Put them in resource files, message files, or a private database.
Use the same resource identifiers throughout the life of the project. Changing identifiers makes it difficult to update localized resources from one build to another.
Make multiple copies of the same string if it is used in multiple contexts. The same string may have different translations in different contexts.
Do not place strings that should not be localized in resources. Leave them as string constants in the source code.
Allocate text buffers dynamically, because text size may expand when translated. If you should use static buffers, make them extra large to accommodate localized strings (e.g., double the English string length).
Keep in mind that dialog boxes may expand due to localization. Thus, a large dialog box that occupies the entire screen in low-resolution mode may have to be resized to an unusable size when localized.
Avoid text in bitmaps and icons, as these are difficult to localize.
Do not create a text message dynamically at runtime, either by concatenating multiple strings or by removing characters from static text. Word order varies by language, so dynamic composition of text in this manner requires code changes to localize to some languages.
Similarly, avoid composing text using multiple insertion parameters in a format string (e.g., in sprintf or wsprintf), because the order of insertion of the arguments changes when translated to some languages.
If localizing to a Middle Eastern language such as Arabic or Hebrew, use the right-to-left layout APIs to layout your application right to left. For details, see the article in the April 1999 issue of the Microsoft Systems Journal at www.microsoft.com/globaldev/articles/singleunicode.asp.
Test localized applications on all language variants of Windows 2000. If your application uses Unicode, as recommended, it should run with no modifications. If it uses a Windows codepage you will need to set the system locale to the appropriate value for your localized application, and reboot, before testing.
A-6. Use 64-Bit Compatible Data Types
It is possible for developers to use a single source-code-base for their Win32-and Win64-based applications. Microsoft has added this support by introducing new data types in the Platform SDK for Windows 2000.
There are three classes of new data types: fixed-precision data types, pointer-precision types, and specific pointer-precision types. These types were added to the Windows environment (specifically, to-basetsd.h) to allow developers to prepare for 64-bit Windows well before its introduction. These new types were derived from the basic C-language integer and long types, so they work in existing code. You can use these data types in your code now, test your code as a Win32-based application, and recompile as a Win64-based application when 64-bit Windows is available
Fixed-precision data types
Fixed-precision data types are the same length in both Win32 and Win64 programming. To help you remember this, their precision is part of the name of the data type. The following are the fixed-precision data types:
| Type | Definition |
| DWORD32 | 32-bit unsigned integer |
| DWORD64 | 64-bit unsigned integer |
| INT32 | 32-bit signed integer |
| INT64 | 64-bit signed integer |
| LONG32 | 32-bit signed integer |
| LONG64 | 64-bit signed integer |
| UINT32 | Unsigned INT32 |
| UINT64 | Unsigned INT64 |
| ULONG32 | Unsigned LONG32 |
| ULONG64 | Unsigned LONG64 |
Pointer-precision data types
As the pointer precision changes (that is, as it changes from 32 bits with Win32 code to 64 bits with Win64 code), these data types reflect the precision accordingly. Therefore, it is safe to cast a pointer to one of these types when performing pointer arithmetic; if the pointer precision is 64 bits, the type is 64 bits. The count types also reflect the maximum size to which a pointer can refer. The following are the pointer-precision and count types.
| Type | Definition |
| DWORD_PTR | Unsigned long type for pointer precision. |
| HALF_PTR | Half the size of a pointer. Use within a structure that contains a pointer and two small fields. |
| INT_PTR | Signed integral type for pointer precision. |
| LONG_PTR | Signed long type for pointer precision. |
| SIZE_T | The maximum number of bytes to which a pointer can refer. Use for a count that should span the full range of a pointer. |
| SSIZE_T | Signed SIZE_T. |
| UHALF_PTR | Unsigned HALF_PTR. |
| UINT_PTR | Unsigned INT_PTR. |
| ULONG_PTR | Unsigned LONG_PTR. |
Specific pointer-precision types
There are also new pointer types that explicitly size the pointer. Be cautious when using pointers in 64-bit code. If you declare the pointer using a 32-bit type, the system creates the pointer by truncating a 64-bit pointer. (All pointers are 64 bits on a 64-bit platform.)
| Type | Definition |
| POINTER_32 | A 32-bit pointer. On a 32-bit system, this is a native pointer. On a 64-bit system, this is a truncated 64-bit pointer. |
| POINTER_64 | A 64-bit pointer. On a 64-bit system, this is a native pointer. On a 32-bit system, this is a sign-extended 32-bit pointer.
Note It is not safe to assume the state of the high pointer bit. |
For more details, please see the Microsoft Platform SDK or visit
/library/en-us/win64/win64/getting_ready_for_64_bit_windows.asp.
A-7. Additional Considerations for Cluster Service
This section identifies addition recommendations, above and beyond the core requirements for applications to support cluster service. These additional recommendations will improve performance and availability.
1. Do Not Use System Registry To Store Large Data Structures or Data That Changes Frequently
Server applications may store data in the system registry. The system registry is stored on a local system disk and is not shared or replicated among nodes in the cluster. Cluster Service can replicate system registry keys on behalf of a server application to guarantee that the application, when it moves from one node to another, can always see exactly the same data in the system registry.
To guarantee the consistency of the data, Cluster Service logs changes to the system registry keys, registered for replication, to one of the shared drives. When a server application fails over to another node, Cluster Service looks for any changes logged and rolls them forward to update the system registry on the current node.
Applications that use the system registry to store large data structures or update it frequently may affect the performance of the cluster and can experience long failover times because of the time needed to roll forward all logged updates.
2. Instrument Your Application (Create an Application-Specific Resource DLL) for Improved Monitoring and Failure Detection
To protect your application against software failures, such as application crashes, hangs, and slow response time, you should provide a resource DLL that extends Cluster Service capabilities to monitor and detect failures of your application.
3. Support Multiple Instances of the Same Cluster Resource Type
To fully utilize the capacity of all nodes in the cluster, your application should support active/active mode where multiple instances of your application can coexist on the same cluster.
Active/Active failover and failback capability allows two separate instances of a resource type to be running on different nodes, each working with different data sets residing on different disks on the shared SCSI bus. (This means that, although the data isn't shared, the resource type is active on both nodes. By definition, there can only be one instance of a resource; however, there can be multiple instances of a resource type.) If the instance of the resource type fails on one node, that instance is moved or "failed over" to the next available node. For example, if your resource type is a database manager application, you can run a copy of the database manager resource type on each node. You can then define a particular database (db1) as a resource. With Active/Active capability, you can move db1 from node one to node two by telling the database manager on each node to release and acquire the database, as appropriate. This communication cannot happen with generic application or service resource types.
4. Support Rolling Upgrades of Windows 2000 and the Application
Downtime caused by planned operating system and application upgrades can be minimized by performing a rolling upgrade.
Rolling upgrade is the process of systematically upgrading each cluster node while the other nodes continue to provide service. Administrators perform rolling upgrades in stages, first by failing over all groups on a node, taking the node offline, upgrading the node, bringing it back online, failing back the groups to the node, and repeating this process on all other nodes. During a rolling upgrade, services are unavailable only for the time needed to move them from one node to another.
Cluster service supports rolling upgrades of the operating system. However, it's your responsibility to guarantee that your application will function properly during a rolling upgrade. It is also your responsibility to support rolling upgrades of your application.
5. Support "Combo" Resource If a Large Number of Instances of the Same Resource Can Be Installed on the Same Cluster
Applications that support Active/Active mode allow installing multiple instances of the same resource type. Each instance of a resource uses system resources and contributes to the cluster service overhead. In addition, a maximum number of resources supported by a Cluster Service is limited to 1670.
If your application supports Active/Active mode and a cluster can be configured to have a large number of resources of your application type, it is recommended that you design your resource DLL to monitor and detect failures of all instances of your application using a single "combo" resource.
6. Management Component of the Application Should Detect Cluster Installation and Use Proper Cluster APIs To Start/Stop the Application
Once your application is under the Cluster Service control, it should not use Service Control Manager (SCM) APIs to start/stop services that were configured as cluster resources.
Service Control Manager and Cluster Service do not synchronize their operations. If you used SCM to stop a service, Cluster service would recognize it as a resource failure and would immediately restart the service.
Use GetNodeClusterState API to determine if the Cluster Service was installed and is running on a particular node.
Use ResUtilEnumResources to find if the particular service is under the control of Cluster Service.
7. Provide Cluster-Aware Setup That Can Detect Cluster Installation, Install the Application on All Nodes in the Server Cluster, and Configure the Cluster
Cluster-aware applications are perceived as difficult to install and manage. A cluster-ready application should come with a setup program that makes the application installation process as simple as possible and supports following scenarios:
Complete installation on all nodes in the cluster
Reliable reinstall and repair on one node
Install the application on a newly added node
Reliable and complete uninstall of application on a node evicted from the cluster
Your cluster-aware application setup should perform following actions:
Detect the cluster. Use GetNodeClusterState.
Enumerate all nodes in the cluster. Use ClusterNodeOpenEnum, ClusterNodeEnum, ClusterNodeCloseEnum
Install the application on all available nodes, schedule installation on nodes currently unavailable. Use GetClusterNodeState to determine node state.
Install the application resource DLL on all nodes and register a new resource type with the cluster using CreateClusterResourceType API.
Register the cluster administration extension DLL with the cluster using DllRegisterCluAdminExtension API.
Publish cluster administrator extension DLLs in Class Store to make it available on any workstation where you want to run Cluster administrator.
Configure the cluster; add and configure new resources.
It should also meet the following requirements:
Transacted setup-In the event the installation is not completed on all selected nodes, cluster-aware setup can roll back to the earlier version of the application without error.
Support unattended mode.
8. Provide Remote Administration Capability
Your application should support remote administration.
A-8. Windows Management Instrumentation
Windows Management Instrumentation (WMI) is a key component of Microsoft's Windows management services. WMI provides a consistent and richly descriptive model of the configuration, status, and operational aspects of applications and systems.-based on the Distributed Management Task Force (DMTF) Common Information Model (CIM), WMI supports uniform system, device, and applications management in Windows operating systems.
WMI provides a unifying access mechanism to both standard and proprietary instrumentation methods, allowing applications to be managed both as discrete elements and as integrated and inter-related parts of a larger enterprise. By exposing a common access mechanism to all management instrumentation, WMI simplifies the task of developing well-integrated management applications.
Suggested compliance
Access management data through WMI
Provide management data to WMI
Conform to the rules for extending the CIMV2 namespace
Conform to the rules for defining vendor-specific namespaces
Customer benefits
Customers gain these benefits when products use WMI:
Management and managed products built on broadly adopted industry management standards.
Improved ease of use due to a logically organized, consistent model of Windows and Windows application operation, configuration, and status.
Solutions that manage both local and remote systems and applications transparently through a common, operating system-based management infrastructure.
Implementation information
This section presents recommendations for creating WMI-compliant products. For the purposes of this section, the use of the terms application or product mean both user mode applications with a desktop graphical user interface and applications written as one or more services as well as managed products such as hardware devices.
1. Access Management Data Through WMI
WMI provides access to a wide variety of Windows system management information through the CIMV2 namespace, a Win32 extension of the CIM schema. Using WMI, an application has access to various management objects including Win32, Performance Monitor, Registry, Windows Installer service, Active Directory, and Event Log data.
If your product uses management functions and data provided by the system and/or other products, and that data is available in the CIMV2 namespace, your product should use WMI to access that management information rather than native APIs.
2. Provide Management Data to WMI
If your product has management functions and data that permit control or monitoring of your product by other management applications, it should be exposed through WMI according to the following recommendations (see the WMI SDK for development details and schema extension rules at https://msdn.microsoft.com/downloads/default.asp?URL=/code/topic.asp?URL=/MSDN-FILES/028/000/015/topic.xml):
Use or extend the existing CIM classes in the CIMV2 namespace or create another namespace with new classes that represent the management functions and data.
Rules for extending CIMV2 are documented in the WMI SDK (formerly called the Web-Based Enterprise Management [WBEM] SDK).
In cases where it is not appropriate to add new classes or instances to CIMV2 (as defined by the SDK documentation), a new namespace should be created.
Provide instances for the newly defined classes. This can be done using static instances defined in a Managed Object Format (MOF) file or dynamic instances generated at runtime by a WMI Provider. If instances are provided through an MOF file, the vendor is responsible for ensuring the MOF file is compiled by the WMI MOF compiler during product setup.
If the product generates events, an event Provider should be implemented. The event Provider sends notifications of events to WMI, which then forwards the events to applications registered to receive those events. The implementation guidelines for event Providers are included in the WMI SDK documentation.
3. Rules for Extending the CIMV2 Namespace
If your product extends the CIMV2 namespace, it should conform to the following guidelines:
Notes
Different types of data have different extension rules.
If two subclasses are derived from a class, and if a particular instance is generated by providers of both the subclasses, then WMI will accept one of them and log an error for the second one. In order to avoid such conflicts, subclassing should be done only if you own the instance of the subclass. Accordingly, it is recommended that subclassing should be done only by the manufacturer of the entity that the instance represents.
Application data
The following classes and instances are created automatically when an application is installed using the Windows Installer service. Refer to the 'Settings Data' section below if you are modeling configuration information not created automatically by the Windows Installer Provider:
The application is represented by an instance of Win32_ApplicationService (subclassed from CIM_Service) representing the presence (either advertised or installed) of the application on the system.
The command line used to execute the application is represented by an instance of Win32_CommandLineAccess (subclassed from CIM_ServiceAccessPoint). These are associated with the instances of Win32_ApplicationService using the Win32ApplicationCommandLine association (subclassed from CIM_ServiceAccessBySAP).
The primary components of the application are represented by instances of Win32_SoftwareElement (subclassed from CIM_SoftwareElement). Some examples of primary components are executables, DLLs, and database files.
Application installation configuration is represented by instances of objects subclassed from CIM_Setting. These are associated with the installed Win32_SoftwareElements using the Win32_SoftwareElementResource association.
Installation configuration of the open database connectivity (ODBC) driver is represented by subclasses of the Win32_SettingCheck association.
If the application has configuration information, the information is visible as a subclass of the CIM_Setting class and should be related to the correct instance of the Win32_ApplicationService (that represents the application on the system). The CIM_Setting instance is associated with the Win32_ApplicationService instance using a subclass of the CIM_ElementSetting association class.
Note There may be multiple instances of the CIM_Setting class representing the possible configurations. The configuration information is settable via the CIM_Setting class. However, the current configuration information is typically stored in the Win32_ApplicationService instance.
Settings data
The rules for extending the schema for settings (for example, any settable parameter defined for services, systems, applications or devices) are:
The setting should be expressed through a subclass of the CIM_Setting class.
Note There may be multiple instances of the CIM_Setting class representing the possible configurations. The configuration information is settable via the CIM_Setting class. However, the current configuration information is typically stored in the CIM_ManagedSystemElement descendent instance.
An instance of a subclass of the CIM_ElementSetting association should be defined to establish a relationship between CIM_Setting and the corresponding descendant of CIM_ManagedSystemElement (the service, system, application, or device to which the setting applies).
Statistics data
The rules for extending the schema for statistics are:
Statistics information about a descendant of CIM_ManagedSystemElement should be expressed through a subclass of the CIM_StatisticalInformation class or be included as property data in the object itself.
Where the data is closely coupled with the Managed System Element and should be retrieved as native properties of the object, the data is placed as properties of the object itself (for example, packets transmitted or received on an Ethernet adapter).
Alternately, where the data may not always be available, is derived from existing data, or is not required to manage the object, it should be placed in a subclass of CIM_StatisticalInformation (for example, major, minor, or warning error counts on a device).
The vendor should define an instance of a subclass of the CIM_Statistics association to establish the relationship between CIM_StatisticalInformation and the corresponding descendant of CIM_ManagedSystemElement.
Device data
The rules for extending the schema to represent a device are:
Vendor-specific classes should derive from leaf-most subclasses of CIM_LogicalDevice.
If the device has configuration information, the information should be visible as a subclass of CIM_Setting and should be related to the correct instance of the CIM_LogicalDevice subclass (that represents the device in the system) using a subclass of the CIM_ElementSetting association class.
Note There may be multiple instances of the CIM_Setting class representing the possible configurations. The configuration information is settable via the CIM_Setting class. However, the current configuration information is typically stored in the CIM_ManagedSystemElement descendent instance.
Do not subclass directly from CIM_LogicalDevice. The WMI SDK contains details of the classes that may be subclassed and instantiated.
Computer system data (typically applies to original equipment manufacturers [OEMs])
The rules for extending the schema to represent a computer system are:
The vendor should define a direct subclass from Win32_ComputerSystem.
Do not subclass directly from CIM_UnitaryComputerSystem.
Physical configuration data
The rules for extending the schema to represent physical configuration:
- Vendor-specific classes should derive from leaf-most subclasses of CIM_PhysicalElement unless Microsoft provides a Win32 schema class for the particular Physical Element. In the latter case, the vendor-specific classes should derive from that Win32 class.
Pretesting guidelines
Microsoft is developing tools that will help to automate the verification process for compliance to the WMI recommendations. Please check https://msdn.microsoft.com/downloads/default.asp?URL=/code/topic.asp?URL=/MSDN-FILES/028/000/015/topic.xml for updated information. In the interim, we recommend using CIM Studio to verify the correctness of the schema design. CIM Studio is included with the WMI SDK. To use CIM Studio for pretesting, make sure you have:
Installed the WMI SDK
Created the MOF files with your schema extensions, where applicable
Compiled the schema into the repository using mofcomp.exe, where applicable
Connected to root\CIMV2 namespace
Located the classes you have added to the namespace (Click on the Find button to invoke the search facility)
To pretest correctness of schema extension for application data
Make sure that your product is installed using the Windows Installer service. This will guarantee correct extension of the CIMV2 namespace for the product data.
If your product has configuration information, you should pretest your Settings Data.
To pretest correctness of schema extension for settings data
Make sure that your class is derived from the CIM_Setting class directly or a leaf-most subclass of CIM_Setting.
Make sure you have defined a subclass of the CIM_ElementSetting association that establishes relationship between CIM_Setting and the descendant of CIM_ManagedSystemElement that you have defined for the service, system, application, or device to which the setting applies.
Make sure that your Provider provides dynamic instances of the classes you have defined.
To pretest correctness of schema extension for statistics data
If the statistical data is closely coupled with your Managed Element and should always be retrieved as native properties of the object, make sure that you include the data as properties of the subclass of CIM_ManagedSystemElement.
If the statistical data is not always available, is derived from existing data, or is not required to manage the System Element, make sure that you have defined a subclass of CIM_StatisticalInformation.
Make sure you have defined a subclass of the CIM_Statistics association that establishes a relationship between CIM_StatisticalInformation and the descendant of CIM_ManagedSystemElement for the service, system, application, or device to which the statistics applies.
Make sure that your Provider provides dynamic instances of the classes you have defined.
To pretest correctness of schema extension for device data
Make sure you have defined a subclass of a leaf-most descendant of CIM_LogicalDevice.
Make sure you do not subclass directly from CIM_LogicalDevice.
If the device has configuration information, you should pretest your Settings Data.
Make sure that your Provider provides dynamic instances of the classes you have defined.
To pretest correctness of schema extension for system data
Make sure you have defined a direct subclass of Win32_ComputerSystem.
Make sure that your Provider provides dynamic instances of this class.
To pretest correctness of schema extension for physical configuration data
If Microsoft provides a Win32 schema class for the particular Physical Element used, make sure that you have defined a subclass of it.
If Microsoft does not provide a class for the particular Physical Element used, make sure you have defined a subclass of a leaf-most descendant of CIM_PhysicalElement.
Make sure that your Provider provides dynamic instances of this class.
A-9. Microsoft Management Console (MMC)
MMC is an extensible, common console designed to integrate management tools and functions, and to present a common visualization environment for management applications. Management applications should be designed to take advantage of the features and support provided by MMC to enable them to present a common interface to the user.
Integrating the look and feel of management functionality in this way provides greater efficiency to administrators, who often combine a number of different management tools to solve a particular problem. Having these tools operate in a similar manner is helpful when managing an enterprise environment.
MMC also reduces the time to market for developers of management products by providing the foundation for the user interface of those applications. Developers can extend existing Console functionality or provide new functionality by the creation of one or more Console snap-ins. Snap-ins are the means by which new features and application behavior are added to the Console.
Suggested compliance
Extend the Computer Management and/or the Users and Groups Snap-Ins with a context menu item that conforms to the MMC user interface guidelines for context menu item.
Write an MMC namespace snap-in.
Customer benefits
System administrators in corporate environments gain these benefits when your application uses MMC:
Reduced learning time-A simpler interface and common look and feel for applications helps administrators learn your product more quickly, maximizing the benefit of the product in the shortest time. The Microsoft BackOffice® suite of products uses MMC to give its management-related features a Windows-based visual interface, providing administrators with a familiar interface so they can quickly learn new applications and information.
Logical grouping of functionality-MMC groups management functions into common categories, making it easier for administrators to find the right tool for the task.
Integration of management tools-MMC provides the foundation for the integration of management tools that previously operated in complete isolation of each other. Integrating functionality in this way provides the administrator with the means to solve problems and manage the environment in a more efficient and time sensitive-manner.
Task delegation-MMC allows administrators to define and distribute specific sets of management functionality to other peer or subordinate administrators, removing the clutter of unnecessary application functionality that doesn't pertain to the immediate task.
Leveraging console snap-ins-Custom corporate and third-party applications can take advantage of existing snap-in functionality to minimize the development time of their applications, while at the same time maintaining the advantages of a common look to those applications.
Implementation information
1. Extend the Computer Management and/or Users and Groups Snap-Ins with a Context Menu Item That Conforms to the MMC User Interface Requirements for Context Menu Items
The simplest way to integrate your application with MMC is to add a context menu item to launch your standalone management tool from one or both of the core Windows 2000 snap-ins. Beyond this, tighter integration is achieved by writing a namespace extension to one of these snap-ins. The section below shows you how to create a context menu extension. Complete information on namespace extensions is available in the MMC SDK section of the Microsoft Platform SDK.
Decide which node you need to extend. The Computer Management root node should not have its namespace extended, but it may have its context menu or property pages extended. The example below assumes you are adding a context menu item to the Computer Management root node. If you want to extend a different node, you should use its GUID in place of the one in the following example.
Register your snap-in as described in the MMC section of the Microsoft Platform SDK. In addition, add a value named with your snap-in's GUID under the following registry key:
HKLM\Software\Microsoft\MMC\Nodetypes
{476e6446-aaff-11d0-b944-00c04fd8d5b0}\Extensions/ContextMenuCreate a snap-in that implements IExtendContextMenu(). This snap-in will invoke your standalone tool when the context menu is selected. Place the snap-in at the CCM_INSERTIONPOINTID_3RDPARTY_TASK insertion point. See the MMC SDK documentation in the Microsoft Platform SDK for full details on insertion points. You may find it easier to use the Microsoft Visual C++® 6.0 ATL wizard for MMC.
If you extend the Users and Groups snap-in rather than the Computer Management snap-in, you will have to use the class GUID for the node you extend. The class GUID is found in the Directory Service section of the Microsoft Platform SDK. Use the Directory Service class registration tool found in this section of the SDK, and follow the steps listed earlier in this requirement to replace the Computer Management GUID with the correct one from the Directory Service section.
2. Write an MMC Namespace Snap-In
Microsoft recommends that you write an MMC namespace snap-in as an alternative to extending a context menu. A namespace snap-in offers the greatest value to an MMC user by taking full advantage of MMC features.
If you write a full namespace extension snap-in, follow the guidelines presented in the MMC snap-in author's guide. These guidelines ensure that snap-ins from different products operate consistently.
This guide can be found at www.microsoft.com/management/mmc/.
Pretesting guidelines
To pretest a snap-in
Standalone Mode:
If the snap-in runs in a standalone mode, then load the snap-in in a user-mode Console and ensure the snap-in performs as expected.
Extends Computer Management:
If the snap-in extends Computer Management, then start the Computer Management console file from the Start menu and verify that your snap-in performs as expected.
Extends Users and Groups Snap-In:
If the snap-in extends the Users and Groups snap-in, then start the Users and Groups console file from the Start menu and verify that your snap-in performs as expected.
Context menu extension:
If your snap-in is a context menu extension, then ensure that you do not add separators, that cascading menus are used sparingly and only on the New and Task menus, and that your items appear in the desired order Appendix.
A-10. Expose a COM-Based Scripting Model
All applications should provide a COM-based scripting model, which will allow system administrators and integrators to access the functionality of the application or its configuration information programmatically. The scripting model should be accessible from the Windows Script Host and Active Server Pages.
Suggested compliance
Applications should provide one or more COM components that expose the functionality of the application or its configuration information.
Components should expose Automation (i.e., IDispatch-based) interfaces or dual interfaces.
Applications should provide programmer's documentation describing how to use the scripting model.
Customer benefits
By providing a scripting model, you enable your customers to:
Automate routine configuration and administration tasks
Develop customized user interfaces
Implementation information
Platform SDK, COM and ActiveX® Object Services, Automation describes Automation and how to implement COM components that expose Automation interfaces in C or C++.
"The Basics of Programming Model Design," Dave Stearns, MSDN Library describes how to define the scripting model.
"Building COM Components That Take Full Advantage of Visual Basic and Scripting," Ivo Salmre, MSDN Library describes how to define scripting models, with special emphasis on access from Visual Basic® and scripting languages.
Visual Basic Component Tools Guide, Creating ActiveX Components describes how to implement COM components that expose Automation interfaces using Visual Basic.
A-11. Use COM+ for Distributed Applications
Your server-based applications should be configured as COM+ applications to take advantage of the benefits provided by COM+. Use the Component Services snap-in for MMC to add your application to the COM+ Applications folder for the computer on which it is installed.
Compliance guidelines
COM+ applications are created from one or more components that use COM+ services and are installed in the COM+ catalog.
All components should be implemented in a dynamic-link library (DLL).
Each component should expose one or more Automation (i.e., IDispatch-based) or dual interfaces.
Use the Component Services snap-in for MMC or the COM+ Administration APIs to register each COM component as part of a single COM+ application.
Use the Component Services snap-in for MMC or the COM+ Administration APIs to export the COM+ application.
Use the Component Services snap-in for MMC or the COM+ Administration APIs to export information required by remote clients to access the COM+ application.
Provide documentation for each COM component.
Describe the syntax and expected results for every method on every interface intended for use by developers or administrators.
Customer benefit
COM+ defines a general purpose programming model for building distributed component-based server applications. Developers architect, design, and build their application servers as COM+ Components to be hosted in COM+ Applications that in turn leverage the Windows 2000 Component Services run-time (also known as the COM+ Services run-time). This execution environment provides the high scalability, robustness, and integrity traditionally associated only with high-end transaction processing systems. The COM+ execution environment automatically and transparently handles the complexities and details of transaction management, including: synchronization of shared resources, process and thread management, context management, role-based security and load balancing.
A COM+ application is a set of one or more in-process components installed in the COM+ catalog. COM+ applications are started on demand, without user intervention. The catalog can contain logon and security information for an application so that it can run although no user is logged on. System administrators can also customize security requirements for each application and thereby control access to it.
COM+ applications may be installed and controlled using standard user and Win32 APIs. Applications can be controlled both locally and remotely through the Component Services administrative tool, providing network administrators an easy and consistent way to control the application across the network.
The Platform SDK provides more information on building and deploying COM+ Applications.
Implementation information
See the Microsoft COM+ Web site for more information on developing COM+ applications: www.microsoft.com/com/.
The Component Services Programmer's Guide describes how to implement COM+ User Events.
Platform SDK, COM and ActiveX Object Services, Automation describes Automation and how to implement COM components that expose Automation interfaces in Microsoft C® or C++® development systems.
msdn_basicpmd.htm">"The Basics of Programming Model Design" by Dave Stearns, MSDN Library, describes how to define the scripting model.
msdn_vbscriptcom.htm">"Building COM Components That Take Full Advantage of Visual Basic and Scripting" by Ivo Salmre, MSDN Library, describes how to define scripting models, with special emphasis on access from Visual Basic and scripting languages.
Visual Basic Component Tools Guide, Creating ActiveX Components describes how to implement COM components that expose Automation interfaces using Microsoft Visual Basic®.
A-12. Run Without NetBIOS in Windows 2000-Only Environment
It is possible to configure a Windows 2000-only environment to run without NetBIOS, and without the NetBIOS name service (i.e., the Windows Internet Name System-WINS).
Therefore, to ensure that applications can run in a Windows 2000-only environment:
Applications must be able to accept as user input both NetBIOS and DNS names for computers and domains.
Applications that run only on the Windows 2000 platform and obtain names programmatically must always request the DNS version of the computer or domain name.
Definitions of maximum computer name length and name validation APIs are discussed in the Active Directory Programmer's Guide.
Working with computer names
For applications that run exclusively on the Windows 2000 platform:
Call GetComputerNameEx and request ComputerNameDnsFullyQualified to obtain the local computer name. This API supercedes GetComputerName on the Windows 2000 platform.
Call SetComputerNameEx and pass ComputerNameDnsHostname or ComputerNameDnsDomain as appropriate to set the local fully qualified computer name. This API supercedes SetComputerName on the Windows 2000 platform.
For applications designed to run on all platforms that handle computer names in Unicode format, the WSALookupService family of APIs should be used for computer name resolution instead of gethostbyname.
Working with domain names
To resolve domain names to Domain Controller names:
Call DsGetDcName with flag DS_PDC_REQUIRED to obtain the name of the Primary Domain Controller for a given domain. This API supercedes NetGetDCName on all platforms.
Call DsGetDcName to obtain the name of any Domain Controller for a given domain. This API supercedes NetGetAnyDCName on all platforms.