sql-server-samples/samples/features/master-data-services/Security/README.md

Master Data Services Security API Sample

This is a C# sample code to show how to export security information into the specified file and import security information from the file by using MDS APIs.

Export security information method gets the security information (the security principals) from the specified MDS application and exports (serializes) it to the specified file (the file will be created in the folder where the sample application runs). Import security information method gets (deserializes) the user and group security principals from the file and clones them (creates them with the same GUIDs) in the target MDS application.

This sample code takes the following parameters.

1. Mode (the first parameter) This parameter indicates whether the code exports or imports the security information. Export: The code exports the security information. Import: The code imports the security information.
2. MDS Host Name (the second parameter) This parameter indicates the host name of the MDS web site. For example, if the MDS URL is http://mydomain.com/mds MDS Host Name is "mydomain.com". If the mode is “Export” it is the host name from which the security information is exported. If the mode is “Import” it is the host name to which the security information is imported.
3. MDS Application Name (the third parameter) This parameter indicates the MDS Application name. For example, if the MDS URL is http://mydomain.com/mds MDS Application Name is "mds".
4. File name (the fourth parameter) The name of the file that stores the security information for users and groups.
5. Exclude Metadata Model Permissions (the fifth parameter) This is an optional parameter that indicates if Metadata Model Permissions are excluded or not. When "ExcludeMetadata" is specified here Metadata Model Permissions are excluded. When Metadata Model's GUID in the target MDS application is different from the one in the source MDS application, the import of the security information fails. To avoid this issue the user can exclude Metadata Model Permissions.

The import of the security information creates users and user groups that were exported from the source MDS application data, so there should not be any user and user group in the target MDS application data that are the same as the source MDS application data. Before the security privileges on models and member hierarchies are imported, the target MDS application should have the same models and member hierarchies with the same GUIDs. Model Deployment can deploy models (other than Metadata) with the same GUIDs.

Program.cs uses Reference.cs (the service reference class file) that was generated by using Visual Studio to access MDS Web service API. You may need to regenerate Reference.cs in case when MDS Web service API is changed.

To generate Reference.cs using Visual Studio:

You need to expose the WSDL. Exposing the WSDL is only necessary at the time when 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.

To enable an http/https Get on the WSDL:

1. Open the MDS web.config file in a text editor (\Microsoft SQL Server\Master Data Services\WebApplication\web.config).
2. Search 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):

1. Search for the tag ‘serviceDebug’ and set includeExceptionDetailInFaults to true.

After that you need to add a Service Reference to http://ServerName/MdsSiteName/service/service.svc and set the namespace to the service to "MDSTestService" in the following steps using Visual Studio.

1. Click "Add Service Reference".
2. In Address, enter the URL to the MDS service which will be “http://ServerName/MdsSiteName/service/service.svc”.
3. Specify the namespace to the service as "MDSTestService" in the Namespace box.
4. Click the Advanced button to configure advanced settings.
5. Check Always generate message contracts.
6. Set the Collection type drop-down to System.Collections.ObjectModel.Collection.
7. Click OK to return to the Add Service Reference dialog.
8. Click OK.

Reference.cs will be generated in Security\Service References\MDSTestService folder. You can replace Security\Reference.cs with the newly generated one.