Master Data Services Team : API

Creating Entities using the MDS WCF API

mattande — Fri, 29 Jan 2010 19:03:00 GMT

(this post was contributed by Brent McBride, Senior Software Engineer on the MDS team).

The below example shows how to create a new model and add new entities in the same call to the MetadataCreate API operation:

Example 1: Add a model and its entities in the same operation.

// Add a new model.

string modelName = "My New Model Name";

Metadata metaData = new Metadata();

metaData.Models = new List<Model> {

new Model() {

Identifier = new Identifier() { Name = modelName } } };

// Add new entities to the new model.

foreach (string entityName in entityNames)

{

Entity entity = new Entity();

entity.Identifier = new ModelContextIdentifier();

entity.Identifier.Name = entityName;

metaData.Models[0].Entities.Add(entity);

}

OperationResult operationResult = new OperationResult();

client.MetadataCreate(international, metaData, true, out operationResult);

The Metadata DataContract contains several properties that are lists of metadata objects, such as Models, Entities, Versions, Attributes, etc. However, in any single call to a metadata CRUD operation (including MetadataCreate), only one of these properties may be non-empty. Otherwise, the operation returns error 200000 “The operation permits only one metadata property list.” Thus, Example 2 is invalid:

Example 2: Incorrectly add model and entities.

// Add a new model.

string modelName = "My New Model Name";

Metadata metaData = new Metadata();

metaData.Models = new List<Model> {

new Model() {

Identifier = new Identifier() { Name = modelName } } };

// Add new entities to the new model.

metaData.Entities = new List<Entity>();

foreach (string entityName in entityNames)

{

Entity entity = new Entity();

entity.Identifier = new ModelContextIdentifier();

entity.Identifier.Name = entityName;

metaData.Entities.Add(entity); // Error! Both Models and Entities cannot be populated.

}

OperationResult operationResult = new OperationResult();

client.MetadataCreate(international, metaData, true, out operationResult);

// Result: Error 200000

The new entities must be added directly underneath the new model to which they belong, as per Example 1. However, the Metadata.Entities property comes in handy when adding entities to an already existing model, as Example 3 shows:

Example 3: Add entities to a preexisting model.

// Reference an existing model.

string modelName = "My Existing Model Name";

Metadata metaData = new Metadata();

// Add new entities to the existing model.

metaData.Entities = new List<Entity>();

foreach (string entityName in entityNames)

{

Entity entity = new Entity();

entity.Identifier = new ModelContextIdentifier();

entity.Identifier.Name = entityName;

entity.Identifier.ModelId = new Identifier { Name = modelName };

metaData.Entities.Add(entity); // No error this time because the Models property is empty.

}

OperationResult operationResult = new OperationResult();

client.MetadataCreate(international, metaData, true, out operationResult);

As shown in the highlighted line of Example 3, each entity must reference the model to which it pertains. Without this context, the operation returns error 120003 “The user does not have permission or the object ID not valid”. This error message is intentionally ambiguous for the sake of security. Using the same error code for both insufficient permissions and invalid IDs makes it harder for an attacker to glean information about the attack surface. Although Example 3 only deals with creating entities, the same principle could also apply to other API operations and metadata objects such as attributes. Error 120003 could occur if there is not enough contextual information provided for the operation to uniquely identify a referenced metadata object.

© 2010 Microsoft Corporation. All rights reserved. This information is provided “as-is”. Information and views expressed, including URL and other Internet Web site references, may change without notice. You bear the risk of using this information. Examples are provided for illustration only. Provision of this information does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this information for your internal, reference purposes only.

Getting Started with the Web Services API in SQL Server 2008 R2 Master Data Services

mattande — Tue, 12 Jan 2010 22:00:25 GMT

(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 Server\Master Data Services\WebApplication\web.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">   <serviceMetadata httpGetEnabled="true" httpsGetEnabled="false" />  <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) { } } }

Add a Service Reference

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.

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).

Create a Simple Client Program

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); } } }

Calling Web Service Operations via the Proxy Methods

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.

The Basics of Service Operations / Proxy Methods

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 Example

Next, 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.

More on Bindings

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.

             // 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();       
               // binding settings such as the following may be set here or in app.config       
               wsBinding.CloseTimeout = TimeSpan.FromMinutes(30);       
               wsBinding.OpenTimeout = TimeSpan.FromMinutes(30);       
               wsBinding.SendTimeout = TimeSpan.FromMinutes(30);       
               wsBinding.ReceiveTimeout = TimeSpan.FromMinutes(30);       
               wsBinding.MaxReceivedMessageSize = 999999999;       
               wsBinding.MaxBufferPoolSize = 999999999;       
               XmlDictionaryReaderQuotas ReaderQuotas = new XmlDictionaryReaderQuotas();       
               ReaderQuotas.MaxArrayLength = 999999999;       
               ReaderQuotas.MaxBytesPerRead = 999999999;       
               ReaderQuotas.MaxDepth = 999999999;       
               ReaderQuotas.MaxNameTableCharCount = 999999999;       
               ReaderQuotas.MaxStringContentLength = 999999999;       
               wsBinding.ReaderQuotas = ReaderQuotas;       
               wsBinding.Security.Mode = System.ServiceModel.SecurityMode.Message;       
               wsBinding.Security.Message.ClientCredentialType = System.ServiceModel.MessageCredentialType.Windows;       
      
               // create and return the client proxy       
               return new ServiceClient(wsBinding, endptAddress);       
          }

Setting the properties of XMLDictionaryReaderQuotas requires the following additional reference line in the program.

   using System.Xml;

Further Recommendations

The preceding example was very basic. To create a more robust, object-oriented solution, I recommend creating an “MDSServiceWrapper” class that encapsulates mdsProxy and its service methods and exposes granular, purpose-built methods such as CreateModel, CreateEntity, etc. This approach would yield a reusable API wrapper that cleanly separates the body of your application from calls to the MDS API.

API Quick Reference

The following information is a brief reference, listing the operation stereotypes and links to further MSDN documentation. The Master Data Services – Technical Reference in SQL Server 2008 R2 Books Online currently provides the lists of operations and classes.

Operation Stereotypes

The following operation stereotypes are defined for consistency. Understanding the functional patterns implemented by each stereotype helps you understand how to use the operations properly, how to form valid requests and what to expect in responses.

Note the term “ID” is used generically. This may be a GUID, member code or other unique ID as appropriate to the type of data.

Get operations…

search for items by ID’s and/or names and return matched items in their response
may make use of “<objectType>SearchCriteria” parameters that act as a filter on the retrieved items
may make use of “<objectType>GetCriteria”, not SearchCriteria, when the criteria are explicit, exact matches
may also use “<objectType>ResultCriteria” parameters that define the information to be retrieved on the matched items

If you were to think of the Criteria parameters in the form of a SQL-like expression, they would be represented as:

SELECT ResultCriteria WHERE records match SearchCriteria

Create operations…

create new items that do not exist
error when the item to be created already exists (matching context and name exists)
require names for new items in the request and assign new internal ID’s to the created items
ignore ID’s that are provided in the request data
may include a “ReturnCreatedItems” option to respond with the ID’s of newly created items

Clone operations…

create items within an MDS instance as exact copies of items from another MDS instance, including the ID’s
require an ID along with a name for creation of the new item
assign both the supplied ID and name to the newly created item
update existing items that are matched by ID

Update operations…

modify existing items and never create new items
error when the item to be modified is not found by its ID

Delete operations…

remove or deactivate existing items by ID
error when the item to be deleted is not found by its ID
may be overloaded with an Undelete option for items such as master data that can be deactivated (soft-deleted)

Merge operations…

automatically create new items or update existing items as appropriate
are only implemented for master data members

Typical functions / operations for editing would include three distinct operations for creating, updating and deleting. This approach is sufficient but sometimes requires extra work by the user. When there is a mix of pre-existing and new items, the user may need to issue additional commands to determine what pre-exists to conditionally execute create or update requests to avoid errors. MDS provides “Merge” operations for master data so the user may avoid these extra steps that increase coding time and complexity.

List of Operations

Refer to the list of Service Methods on MSDN.

Web Service Class Reference

Visit the MDS Web Service Class Reference on MSDN to look up class descriptions for the message and data contracts of the services.

Master Data Services Team : API

Creating Entities using the MDS WCF API

Getting Started with the Web Services API in SQL Server 2008 R2 Master Data Services

Enable Web Services in Configuration Manager

Expose the WSDL

Create an Example Application in Visual Studio

Add a Service Reference

Advanced Settings

Create a Simple Client Program

Calling Web Service Operations via the Proxy Methods

The Basics of Service Operations / Proxy Methods

Completing the Example

Try it Out

More on Bindings

Further Recommendations

API Quick Reference

Operation Stereotypes

List of Operations

Web Service Class Reference

Legal Notice