Computer Management Provider API

Article
04/19/2010

This document provides the details of the application programming interface (API) for the Computer Management Provider included with the Microsoft Provisioning System (MPS) in the . Contained herein are descriptions of the procedures of this provider along with method input parameters and return values. In addition, example Extensible Markup Language (XML) requests are provided along with a typical XML response that the provisioning system returns after a request is submitted to MPS and tasks are completed.

Developers should use this API document as a reference when creating XML requests that initiate computer management provisioning tasks. The intended use of this API is for client applications that will perform provisioning tasks that are specific to computer management.

Overview

The Computer Management Provider is a new provider for , that supplies a set of public methods for local computer management provisioning. The namespace enables Service Providers to provision computer management to customer organizations and users through the managed provisioning environment of MPS, using the Microsoft Provisioning Framework (MPF) Engine, version 2.1.

Provisioning objects such as users, groups, and services at the local machine level is growing increasingly important to solutions built on MPS. Also, many of the new setup and framework components benefit from the ability to communicate with the local machine subsystem.

The Computer Management Provider focuses on management functions of individual machines such as creating machine-local accounts, restarting services, setting rights, and so on. The ability to utilize the functionality of the Computer Management Provider facilitates the following benefits:

Increases the core features of MPS and broadens the scope of manageable services.
Increases the number of steps that can be automated in the setup and deployment of the provisioning solution.
Gives Service Providers increased control over their hosting infrastructure for a single unified platform.
Allows Service Providers to broaden the number of services they can provision and interact with from MPS.

Provisioning Actions

The Computer Management Provider is implemented as a standard MPF provider. It exposes interfaces to the MPF engine for low-level computer management tasks. These interfaces encapsulate methods that do the following:

Create SAM objects such as users and groups.
Control local machine services.
Add users and groups to (or remove them from) local security policies.
Retrieve local machine information.

Implementation

The Computer Management Provider is Active Directory-neutral, meaning that MPS can provision to the local machine regardless of whether or not that machine is a member of a domain. The Computer Management Provider includes two main classes of methods to provide better abstraction between the methods doing the work and those that interact with MPS. The first class comprises all the methods required for interacting with the local machine. The second class is a wrapper class to wrap the base methods in the first class and to interact with MPS, as shown in Figure CMP.1.

Dd279096.c5a3b954-389c-4ef7-a93f-97bbe460ad57(en-us,TechNet.10).gif

Figure CMP.1: Computer Management Provider class implementation

In order to connect and authenticate, each method is overloaded to allow the method to be called with or without supplying credentials. If credentials are not specified, the account of the logged-on user will be used by default.

Note

You install the Computer Management Provider with the MPS Deployment Tool.

WinNT Paths

The "Paths" recognized by this provider are valid paths as supported by the WinNT provider for ADSI. The path may or may not contain the domain component and the object type (class). The following formats are exemplary of various formats available:

WinNT://<domainName>/<computerName>/<object>,<objectType>
WinNT://<computerName>/<object>,<objectType>
WinNT://<computerName>
WinNT://FABRIKAM/MyServer/MyUser,user

Dependencies

The following dependencies apply to the Computer Management Provider:

The provider and MPS run on Windows Server 2003, SP1.
Target local machines run on Windows Server 2003.
The provider is built with Microsoft Visual Studio 2003, is written in C#, and leverages the .NET 1.1 Framework's System.Management and System.DirectoryServices namespaces to communicate with WMI and ADSI APIs.
The provider utilizes the MPF .Net Provider base class.

Application Scenarios

Several points in the scenarios below are common to all of them. The Computer Management Provider runs under the MPF engine, which is only hosted on Windows 2003. It is intended to control and manage Windows ServerT 2003 installations only, running Service Pack (SP) 1 or later.

Windows 2003 Server Setup and Deployment-Setup and deployment of Windows 2003 Server is the primary configuration that is supported. Windows 2003 Servers can comprise a number of roles, such as Active Directory directory services domain controller, Exchange Server, SQL ServerT, or Web Server. In some instances, it is valuable to be able to communicate directly with the local machine subsystem to perform tasks such as creating users, restarting services, or setting permissions.

For example, during the deployment of the Hosted Messaging and Collaboration, version 3.5 solution, it is a requirement to configure the MPFServiceAccts group as an administrator on the machine hosting the MPF engine. The MPS Deployment Tool utilizes the functionality of the Computer Management Provider to automate the setup of this step.
Windows 2003 Server Provisioning-With the Computer Management Provider, Service Providers can implement other provisioning actions that configure and manage the local computer. For example, the Service Provider could create a user to run an application pool of static sites for a customer. This can be rolled into a single provisioning transaction with the use of the Computer Management Provider to create user accounts and add them to the required groups.

Public Methods

Public Method	Description
Computer Management Provider::Create Object	Allows you to create a WinNT object on the designated server.
Computer Management Provider::Delete Object	Allows you to delete a WinNT object on the designated server.
Computer Management Provider::Rename Object	Allows you to rename a WinNT object on the designated server.
Computer Management Provider::Get Properties	Allows you to get the properties of a WinNT object using Active Directory Service Interfaces (ADSI).
Computer Management Provider::Set Properties	Allows you to set a property or collection of properties on a WinNT object.
Computer Management Provider::Enumerate Objects	Allows you to view the collection of child objects of a specific object, given the object class.
Computer Management Provider::User Set Password	Allows you to set the password for a given user object.
Computer Management Provider::User Change Password	Allows you to change the password for a given user object.
Computer Management Provider::Group Add	Allows you to add users and groups to a group on the designated server.
Computer Management Provider::Group Remove	Allows you to remove users and groups from a group object on a designated server.
Computer Management Provider::Group IsMember	Returns a list of the members of a specified group.
Computer Management Provider::Group Members	Returns a list of the members of a specified group.
Computer Management Provider::Control Service	Allows you to control a service on a designated server.
Computer Management Provider::Get Machine Configuration	Allows you to retrieve the configuration of a specified server.
Computer Management Provider::GetNTRightsAssignment	Allows you to enumerate the users and groups that hold a specified privilege or right.
Computer Management Provider::SetNTRightsAssignment	Allows you to add a privilege (right) to a specific user or group.
Computer Management Provider::RemoveNTRightsAssignment	Allows you to remove a privilege (right) from a specific user or group.
Computer Management Provider::Get Service Status	Retrieves the status of a specified service.
Computer Management Provider::Set Service Credentials	Allows you to set specific start-up credentials for a service.

Applies To

Hosted Messaging and Collaboration version 4.5
Hosted Messaging and Collaboration version 4.0
Hosted Messaging and Collaboration version 3.5
Windows-based Hosting version 4.5
Windows-based Hosting version 4.0
Windows-based Hosting for Applications version 1.0

Computer Management Provider API

Applies To

Additional resources