Share via

Get Started with Microsoft Provisioning System SDK

  • Article

Visual Studio 2005 is the integrated development environment (IDE) of choice when it comes to development tasks of all kinds for the Microsoft Hosted Solutions. This newest version of the Microsoft Provisioning System Software Development Kit (MPS SDK) enables the developer to more easily use the power of Visual Studio when developing features that will use the Microsoft Provisioning System.

This documentation provides an overview of these tools, including the available code samples and templates, and how to use them within the IDEs for Visual Studio 2003 and 2005.

Features of the MPS SDK

The MPS SDK includes the following features:

  • Provider wizard for C# integrated into Visual Studio .NET 2003

  • Intellisense for Named Procedures and requests integrated into Visual Studio .NET 2003

  • Provider wizard for VB.NET integrated into Visual Studio 2005

  • Provider wizard for C# integrated into Visual Studio 2005

  • Intellisense for Named Procedures and requests integrated into Visual Studio 2005

  • Visual Studio 2003 samples of providers are written in C# and targeted at the 1.1 release of the .NET Framework. Visual Studio 2005 Samples are written in C# and/or VB.NET and are targeted at the 2.0 release of the .NET Framework.

  • Integration of various MPS development tools into the Visual Studio 2005 IDE

One of the benefits of MPS is the ability to further customize it to meet the specific needs of businesses. MPS can be extended through the addition of custom providers. Several samples are provided in this SDK to guide you in the beginning steps of writing a provider.

Writing Providers

Writing Providers in Visual Studio.NET 2003

This section uses the SendMail Sample provider, which is located by default at <SystemDrive> Program Files\Microsoft Hosting\Development\Samples\CSharp\1.1\, to introduce how to write a provider in Visual Studio 2003.

In general, there are three steps to perform within the Provider.cs file.

  1. Gather all the input data, if any

  2. Process the data that has come in, if any

  3. Process the output data for the end user to see

Near the top of the Provider.cs file is the header, which is where you must define the name of the method. This name will show up in MPS as a method which can be selected. In the case of the SendMail Provider, the name of the method is Send Mail. Other properties, such as Description and AccessType, can be included in the header as well:

[ProviderMethodAttribute("Send Mail", ProviderHandlerType.process)]

The provider begins by getting the input data. The executeData node is defined first, then the subnodes are placed directly under the executeData node. That section of the SendMail Provider sample looks like the following:

 
// Get the executeData node 
IXMLDOMNode executeDataNode = node.selectSingleNode("/executeXml/executeData"); 
 
// get the required elements 
string recipient = this.GetRequiredElementValue(executeDataNode, "recipient"); 
string sender = this.GetRequiredElementValue(executeDataNode, "sender"); 
string subject = this.GetRequiredElementValue(executeDataNode, "subject"); 
string messageText = this.GetRequiredElementValue(executeDataNode, "messageText"); 
 
// get the optional elements 
string messageFormat = this.GetOptionalElementValue(executeDataNode, "messageFormat"); 
string messagePriority = this.GetOptionalElementValue(executeDataNode, "messagePriority"); 
string smtpServer = this.GetOptionalElementValue(executeDataNode, "smtpServer"); 
string smtpUser = this.GetOptionalElementValue(executeDataNode, "smtpUser"); 
string smtpPassword = this.GetOptionalElementValue(executeDataNode, "smtpPassword");

The GetRequiredElementValue and GetOptionalElementValue methods are public helper methods that the user can see in the lower sections of the code. After grabbing the input data, the next step is to process the data and assign it to a response object that we can use for the output. This processing is assigned in the following statement from our SendMail sample:

string response = this.SendTheMail(sender, recipient, subject, messageText, 
        messageFormat, messagePriority, smtpServer, smtpUser, smtpPassword);

The SendMail sample calls the SendTheMail method, which processes the input and returns a simple response. So the only step remaining for the Provider.cs file is to return the output. The SendMail sample looks like this:

AddOutputNode(node.ownerDocument, (IXMLDOMElement)executeDataNode, "status", 
        response);

In this statement, the executeDataNode is sent, then the code defines the name of the node that will contain the response (status), and then finally the text of the response is declared. Lastly, the project is built (CTRL+SHIFT+B).

Prepare the Namespace File

In order for MPS to know what the provider can do, the next step is to create the XML description of the provider. Open the Provider_NS.XML file in the SendMail sample project. This particular file is longer than required because of the schema information that is included in the sample. The only required part of the file is the upper header portions.

After the XML file is finished, save it. Open Provisioning Manager and import the SendMail namespace. After importing the namespace, the entry "SDK Send Mail Provider" should appear in the left-hand column. When you clicking SDK Send Mail Provider, a procedure named Send Mail should appear in the right-hand column. The last thing to do is create a "SendMail" request that will call the provider that has been created. In order to start a new request, in Visual Studio, use one of the new Develop Custom Providers [HMC SDK1] provided in the SDK. Click File, and then click New File, and then open the template for MPSRequest. A sample request file for the SendMail provider is shown below:

<namespace name="SDK Send Mail Provider"  
                    providerSource="SendMailProvider.Provider" 
                    xmlns:xsl="https://www.w3.org/1999/XSL/Transform" 
                    description=""> 
 
      <procedure name="Send Mail" type="write" access="private" description="Sends a mail message against an SMTP server"> 
      <Schema name="inputSchema">

After saving the request, go to a command prompt and run the request. The response will be enveloped in the "status" node and should say, "Your message was sent successfully."

Writing Providers in Visual Studio.NET 2005

This section uses the SendMail Sample provider, which is located by default at <SystemDrive> Program Files\Microsoft Hosting\Development\Samples\CSharp\2.0\, to introduce how to write a provider in Visual Studio 2005.

Open the SendMail sample provider by opening the project, by default located at: C:\Program Files\Microsoft Hosting\Development\VS2005\CSharp\2.0\SendMail. The Provider Attribute header specifies the name of provider that is being built. In the SendMail sample, it looks like this:

[ProviderAttribute("SDK Send Mail Provider CS", "Sample provider written in C#")]

The ProviderMethodAttribute header specifies the name of a method within the provider.

 
[ProviderMethodAttribute("Send Mail", ProviderMethodType.MethodTypeRead, 
                         Description = "Sends a mail message against an SMTP server")]

Notice that the method type is .MethodTypeRead. A read method does not require any rollback action. If this were a MethodTypeWrite, then a rollback method would need to be added to this project. The Windows Media Provider Sample has three methods, and shows how to handle Write methods. In short, a rollback method is required, and the name of the rollback method is by default the name of the method, plus the word "rollback" appended to the end.

Within the main block of the code, the first item performed in our samples is to build the resource name into a string. For our example, the variable resource name takes on the value: "SendMailProviderCS.Data.Send Mail_Request.xsd".

string resourceName = string.Format("{0}.{1}", this.GetType().Namespace, "Data.Send Mail_Request.xsd");

Next, the xmlHelper object builds an XML document, and then you use the schema that was built to validate the XML document.

XmlHelper xmlHelper = new XmlHelper(node, this.GetType().Assembly); 
        xmlHelper.ValidateSchema("SendMailRequest", "Send Mail_Request.xsd", resourceName);

Now you deserialize the input into the object data structure. This will break down all of the nodes for use and manipulation.

SendMailRequest data = (SendMailRequest)xmlHelper.DeserializeInput(typeof(SendMailRequest), 
 "Send Mail_Request.xsd");

Once all of the nodes are broken down, the provider gets used to actually perform whatever action is necessary for the provider to meet the required logic. In this case, the sample is processing an e-mail message.

SendMailResponse response = SendTheMail(data);

Finally, you return the response if any. Notice that you call the SerializeOutput method in order to reassemble your data nodes, then return the required response to the caller.

node = xmlHelper.SerializeToOutput(typeof(SendMailResponse), response);

After the code is finished, build the project. Ensure that all of the MPS SDK tools are showing. Click Show All Files in the Solution Explorer. Under the project, under bin, and then under Debug, right-click the <namespaceName>_NS.xml file, and then choose Register the namespace. The namespace explorer should now have the namespace listed. With the project still open, navigate to the namespace you just registered in the namespace browser, click the plus sign next to the namespace, right-click the Send Mail method, and then choose Create Sample Request. A new XML file will be created in the project. Change the input settings, right-click the request, and then click Submit the request. The output window will display the results.