Develop Custom Providers

This section contains overviews of the sample providers provided in the Microsoft Provisioning System (MPS) Software Development Kit (SDK). This release of the MPS SDK includes four example features with one sample for each of the three languages listed below:

The example features included in this SDK are:

Visual Studio 2003 versus Visual Studio 2005

With Visual Studio 2005, developers gain the benefits of a fully integrated development environment, including schema-based validation and the ability to debug as code is written. Visual Studio 2003 features include development templates and API reference integration. C# is the only language supported for MPS providers in Visual Studio 2003, whereas with Visual Studio 2005 both C# and VB.net are supported. The C# provider wizard is available to both Visual Studio 2003 and 2005. The VB.NET wizard is available only with Visual Studio 2005.

While schema validation is extremely useful in Visual Studio 2005, it is not available in Visual Studio 2003. With each project created by the Visual Studio 2003 Provider Wizard, a provider namespace file will be placed within the project. Input and output schema are also included as a best practice, however the code will not be able to validate against the schema.

Provider Wizards Usage

With Visual Studio 2003, a template add-in is available to help you get started writing a new provider more quickly. This feature is only available for C# development projects.

The MPS SDK add-ins to Visual Studio 2005 make creating a new project for developing a provider even easier. You can choose to develop in C# or VB.NET once you have selected an MPS Provider project. This approach allows you to build on the base class, an assembly that provides the interoperability layer between the MPS engine and the .NET framework. You also have access to utility classes and methods for validating input and structuring output.

Using the C# Provider Wizard
To use the C# Provider Wizard in Visual Studio 2003
  1. In Visual Studio 2003, on the File menu, point to New, and then click Project.
  2. In the New Project dialog box, on the Project Types page, select Visual C# Projects.
  3. In the Templates selection window, select the new project type MPSProvider. Complete the Name, Location, and New Solution Name text boxes, and then click OK.
The wizard then creates a project, establishes the proper references, creates the initial class file, and the stub for a provider namespace.
To use the C# Provider Wizard in Visual Studio 2005
  1. Open Visual Studio 2005.
  2. On the File menu, point to New, and then click Project.
  3. Under Microsoft Provisioning System, choose MPS Provider.
  4. Choose a name for the provider and a location.
  5. If a security warning window pops up, click Load Project Normally, and then click OK.

Now, when you view the code in the Provider.CS file, you will see a base provider built on the base class. This base class performs all the functions expected from an MPS Provider, such as receiving and returning XML data (<executeData> and <response>). A sample provider that can be tested will appear. All you need to do is to add the logic to accept input data, process it, and return the responses back to the user.

Using the Visual Basic .NET Provider Wizard

Because Visual Basic .NET requires explicit ByRef calls, the MPS base class has been modified to support this requirement. Visual Basic developers are required to call the new parameterized constructor, passing a value of "true." Also, provider methods must have a ByRef flag along with the appropriate parameters.

Item Templates Usage

Item templates help a developer quickly begin a request or a namespace. The templates available in this SDK are MPS Request.xml and MPS Namespace.xml. The means of accessing these templates are the same in Visual Studio 2003 and 2005.

To open an item template in Visual Studio
  1. In Visual Studio, on the File menu, point to New, and then click File.
  2. Under General, select MPS Request.xml.

As a result, the following code will appear:

<?xml version="1.0" encoding="iso-8859-1" ?> 
<request xmlns="http://provisioning.microsoft.com/MPF" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <data/>
  <procedure>
	<execute namespace="" procedure="">
	<before source="data" destination="executeData" mode="merge"/>
	<after source="executeData" destination="data" mode="insert"/>
	</execute>
  </procedure>
</request>
Schema-based Validation

Schema-based validation is not required for writing MPS providers. Using it enables you to ensure that your code is conformant with the schema while the code is being developed. Doing so makes it easier to maintain and extend your providers in the future.

Note

Schema-based validation is only available for Visual Studio 2005.

In order to adhere to the schema, you need two Extensible Schema Definition (XSD) files:

To add XSD validation to a provider
  1. In Visual Studio 2005, create a Data folder at the root of the project.
  2. Add a request and a response XSD file to the project under the Data folder.

An excerpt of the Request XSD for the Send SMTP Sample Provider is shown below. In this example, the id attribute and targetNamespace values are not the same. The id is internal to the XSD schema whereas the namespace is an externally available reference. The values differ so that the schema validation tool can distinguish between the two variables. Each provider method requiring input data has a corresponding element in the XSD file and text within the documentation tags is used to explain the purpose of the method. The appinfo attribute contains data that can be used in making a request using this sample provider.

<?xml version="1.0" encoding="iso-8859-1" ?> 
<xs:schema id="Send_Mail_Request" 
				targetNamespace="Send Mail_Request.xsd"
				elementFormDefault="qualified"
				xmlns="Send Mail_Request.xsd"
				xmlns:mstns="Send Mail_Request.xsd"
				xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:annotation>
	<xs:documentation>This method is used to send a single mail message against an SMTP server</xs:documentation>
  </xs:annotation>
  <xs:element name="SendMailRequest">
	<xs:annotation>
	<xs:documentation>Primary data node</xs:documentation>
	</xs:annotation>
	<xs:complexType>
	<xs:all>
		<xs:element name="recipient" minOccurs="1" maxOccurs="1" type="xs:string">
		<xs:annotation>
			<xs:documentation>Email address of the recipient</xs:documentation>
			<xs:appinfo source="http://provisioning.microsoft.com/examples">admin@litwareinc.com</xs:appinfo>
		</xs:annotation>
		</xs:element>
		<xs:element name="sender" minOccurs="1" maxOccurs="1" type="xs:string">
		<xs:annotation>
			<xs:documentation>Email address of the sender</xs:documentation>
			<xs:appinfo source="http://provisioning.microsoft.com/examples">joe@fabrikam.com</xs:appinfo>
		</xs:annotation>
		</xs:element>

For more information on how to validate XML files using an XSD, see How To Validate an XML Document by Using DTD, XDR, or XSD in Visual C# .NET.

Once you have created the XML Schema, you can use the XML Schema Definition Tool (Xsd.exe) to generate runtime classes. These generated classes can then be used, in conjunction with System.XML.Serialization.XMLSerializer, to read and write XML code that follows the schema.

At this point, you can right-click the Data folder and choose to Add an existing item. Browse to include the class files that were just generated, and add those to the project.

Important

At this point, right-click each XSD file in the project and click Properties to open the Properties pane. Verify that Embedded Resource is selected for the Build Action property. Without this property setting, schema validation will not work.

Figure: Verifying the Embedded Resource property setting

Now build the project, and the XSD file validation should be ready to reference in the code. Be sure to reference the SendMail Sample Provider to see how to use the validation techniques.