(this post was contributed by Val Lovicz, Principal Program Manager on the MDS Team)
With the November CTP release available, many have been asking for basic information and examples for programming the Web services API. While MDS conceptual content and API reference are available and updated periodically in SQL Server Books Online , we hope this brief post will help get you started and give you a sense of how to use the Web services API.
This post provides instructions and examples using Visual Studio 2008, .NET and C# and is intended for an audience with a basic understanding of these technologies.
The following are general references on MSDN for working with Web services if you would like more background information.
Enable Web Services in Configuration Manager
Before we get started, make sure your installation of MDS has Web services enabled. The prior post Installing and Configuring Master Data Services provided detailed configuration instructions and included a step to check the Enable Web services for the Web application setting as shown below.
Expose the WSDL
Exposing the WSDL is only necessary at the time you want to generate proxy classes using a client development tool such as Visual Studio. After a proxy has been generated, the WSDL does not need to be exposed going forward for client programs to call the API.
Caution: Updating web.config will cause the MDS application domain in IIS to recycle. Existing user sessions will lose cached information, and users may experience session errors or slow page loads. Perform changes at off-peak times if possible and use non-production environments for development.
To enable an http/https Get on the WSDL:
- Open the MDS web.config file in a text editor (<Program Files>Microsoft SQL ServerMaster Data ServicesWebApplicationweb.config).
- Look for the tag serviceMetadata and set httpGetEnabled to true (or httpsGetEnabled if using SSL).
To also enable service exception details for additional debugging (not necessary for standard, trapped errors):
- Look for the tag serviceDebug and set includeExceptionDetailInFaults to true.
<system.serviceModel>
<behaviors>
<serviceBehaviors>
<behavior name="mdsWsHttpBehavior">
<!-- Enable to allow clients to retrieve metadata (WSDL) about the service endpoints. -->
<!-- If not using SSL (httpGetEnabled="true" httpsGetEnabled="false") to expose service metadata.—>
<!-- If SSL is being used (httpGetEnabled="false" httpsGetEnabled="true") to expose service metadata.-->
<serviceMetadata httpGetEnabled="true" httpsGetEnabled="false" />
<!-- Enable to allow clients to see service exception details -->
<serviceDebug includeExceptionDetailInFaults="true" />
<serviceThrottling maxConcurrentSessions="400"/>
<dataContractSerializer maxItemsInObjectGraph="999999999"/>
</behavior>
</serviceBehaviors>
</behaviors>
…
</system.serviceModel>
Note: these settings will apply to all Web application instances on this server. All instances are virtual directories that point to the same Web files and web.config.
Create an Example Application in Visual Studio
Create a simple Console Application using the following steps.
- In Visual Studio, select File – New – Project…
- In the New Project Dialog, select Visual C# - Windows under Project types
- Select Console Application under Templates
- Enter “HelloMDS” as the Name
- Click OK to create the project
You will now have an empty template program as shown.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
namespace HelloMDS
{
class Program
{
static void Main(string[] args)
{
}
}
}
Next, add a service reference to the project for consuming the MDS Web service.
- In the Solution Explorer window, right-click References
- Click Add Service Reference
You will see the Add Service Reference dialog. Now, configure the service reference.
- In Address , enter the URL to the MDS service which will be “http://<ServerName>/<MdsSiteName>/service/service.svc”. If you do this on the computer where MDS is hosted, you can use “localhost” as the server name.
- Click Go . Visual Studio will attempt to contact the service and retrieve the WSDL.
- If successful, you will see Service and IService in the Services box. Click on IService to preview the list of operations as shown.
- Assign a namespace to the service in the Namespace box. In this example, I am using MDService .
- Click the Advanced button to configure advanced settings.
Here you will change how the proxy classes are generated. This step is only necessary so that your code can be identical to my examples.
- Check Always generate message contracts
- Set the Collection type drop-down to System.Collections.ObjectModel.Collection
- Click OK to return to the Add Service Reference dialog
- Click OK . In the status bar you will see “Generating new service reference to…”. The proxy classes are being generated.
- When VS is ready, you will see the MDService service reference added to your project (shown in Solution Explorer ).
Next, you can use the following example code to expand the template program. The program, as shown below, only contains the minimal steps to initialize a client proxy which you may then use to call MDS Web service operations. You will need to add additional statements to make this program perform useful work. You will need System Administrator access to MDS to successfully run the example application.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
// additional references...
using HelloMDS.MDService; /* for the created service reference */
using System.Collections.ObjectModel; /* supports collection objects used in the proxy */
namespace HelloMDS
{
class Program
{
private static ServiceClient mdsProxy; /* service proxy object */
static void Main(string[] args)
{
// Create the service proxy
Console.WriteLine("Connecting...");
try
{
mdsProxy = CreateMdsProxy("http://localhost/MDS/service/Service.svc");
Console.WriteLine("Connected.");
}
catch (Exception ex)
{
Console.WriteLine("Error connecting: " + ex.Message);
}
// At this point we could start calling methods on mdsProxy to execute Web service operations.
}
// creates the service client proxy
private static ServiceClient CreateMdsProxy(string mdsURL)
{
// create an endpoint address using the URL
System.ServiceModel.EndpointAddress endptAddress = new System.ServiceModel.EndpointAddress(mdsURL);
// create and configure the WS Http binding
System.ServiceModel.WSHttpBinding wsBinding = new System.ServiceModel.WSHttpBinding();
// create and return the client proxy
return new ServiceClient (wsBinding, endptAddress);
}
}
}
Now that a service client object mdsProxy is established in the code, you can begin calling its methods.
For example:
- In the example code above, place the cursor after the line “//At this point we could start…”
- Type “mdsProxy.” and IntelliSense will display the available methods as shown below. Most of these methods correspond directly to MDS Web service operations.
MDS service operations follow the naming convention of NounVerb . For example, the operation to create new metadata objects such as models, entities and hierarchies is MetadataCreate . Each proxy method that represents a service operation will have a single request object parameter (e.g. MetadataCreateRequest ) and will return a response object (e.g. MetadataCreateResponse ). Therefore, a typical call of a proxy method, such as MetadataCreate , would include the following lines.
// Create the request and response objects
MetadataCreateRequest request = new MetadataCreateRequest();
MetadataCreateResponse response = new MetadataCreateResponse();
// Here, we need to populate the request in order to do something useful.
// Make the service request
response = mdsProxy.MetadataCreate(request);
This example calls MetadataCreate without populating the request. You would need to populate the request with a new object for creation, such as a new model, to perform a successful and useful call.
Completing the ExampleNext, you may use the following code example to complete the program. The program below has an added method CreateModel . This method accepts a new model name string parameter and populates the request with the single model name provided.
To complete the example, add the call to CreateModel(“Hello World”); in Main as shown. This will create a new model in the MDS repository, named “Hello World”.
You’ll also notice the addition of the HandleErrors method. Each response includes an OperationResult object which contains a collection of Error objects if any errors are encountered when processing the request. This method example prints the list of operation error messages if any are returned.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
// additional references...
using HelloMDS.MDService; /* for the created service reference */
using System.Collections.ObjectModel; /* supports collection objects used in the proxy */
namespace HelloMDS
{
class Program
{
private static ServiceClient mdsProxy; /* service proxy object */
static void Main(string[] args)
{
// Create the service proxy
Console.WriteLine("Connecting...");
try
{
mdsProxy = CreateMdsProxy("http://localhost/MDS/service/Service.svc");
Console.WriteLine("Connected.");
}
catch (Exception ex)
{
Console.WriteLine("Error connecting: " + ex.Message);
}
CreateModel("Hello World");
}
public static void CreateModel(string newModelName)
{
// Create the request and response objects
MetadataCreateRequest request = new MetadataCreateRequest();
MetadataCreateResponse response = new MetadataCreateResponse();
// Build the request with the new model
request.Metadata = new Metadata();
request.Metadata.Models = new Collection<Model>() { new Model() };
request.Metadata.Models[0].Identifier = new Identifier();
request.Metadata.Models[0].Identifier.Name = newModelName;
// Make the service request to Create.
response = mdsProxy.MetadataCreate(request);
HandleErrors(response.OperationResult);
}
// creates the service client proxy
private static ServiceClient CreateMdsProxy(string mdsURL)
{
// create an endpoint address using the URL
System.ServiceModel.EndpointAddress endptAddress = new System.ServiceModel.EndpointAddress(mdsURL);
// create and configure the WS Http binding
System.ServiceModel.WSHttpBinding wsBinding = new System.ServiceModel.WSHttpBinding();
// create and return the client proxy
return new ServiceClient (wsBinding, endptAddress);
}
// Handles the operations results
private static void HandleErrors(OperationResult result)
{
string errorMessage = string.Empty;
if (result.Errors.Count() != 0)
{
for (int i = 0; i <= result.Errors.Count() - 1; i++)
{
errorMessage += " OperationResult:Error: " + result.Errors[i].Code + ":"
+ result.Errors[i].Description + ":" + result.Errors[i].Context.Type.ToString();
}
Console.WriteLine("Error: " + errorMessage);
}
}
}
}
Try it Out
If you have copied the example code so far, build ( F6 ) and run ( F5 ) your solution to test it. You will briefly see the console application appear and then complete. Verify the results by logging into the Master Data Manager Web application (MDM). You will see “Hello World” added to the list of models on the home page.
Note: MDM caches metadata, so if you already had MDM open in your browser when the HelloMDS application was run, you will not see the newly created model. You would need to click Refresh at the bottom of the Home page or close your browser and reconnect.
As you expand the solution to get or receive larger, more complex messages, you may find the need to increase certain default binding settings. In the example below, the CreateMdsProxy method has been expanded to include additional settings on wsBinding . These settings are not recommended settings for all situations; they merely show how to increase these settings should you run into timeouts or message overflows. These same settings may also be configured in the app.config file within your project. For more information, refer to the MSDN article: Using Bindings to Configure Windows Communication Foundation Services and Clients .