Introduction to the deployment web service

Article
02/23/2018

Applies To: Dynamics 365 (on-premises), Dynamics CRM 2016

The deployment service allows you to create solutions to take advantage of support for multiple organizations—also called multi-tenant support. Microsoft Dynamics 365 enables you to host multiple customer organizations within a single deployment. This capability benefits hosted solutions or businesses that require a separation of data inside the organization. Because using the deployment service requires access to the Dynamics 365 server, it can only be used for Microsoft Dynamics 365 on-premises deployments.

With multiple organization support, the Microsoft Dynamics 365 web application and web services support the storage and retrieval of data across multiple business organizations while maintaining the security and privacy of each individual organization. A single Microsoft Dynamics 365 configuration database stores the metadata and location information for all customer organizations. However, each customer organization has its own database on a server running Microsoft SQL Server. For more information about the entities and configuration settings controlled by the deployment service, see Deployment entities and deployment configuration settings.

Microsoft Dynamics 365 does not support a backward compatible end-point for the deployment service so any code written for the Microsoft Dynamics CRM 4.0 deployment service must be updated and recompiled with the new assembly.

Add the deployment service to your project

You can use the deployment service by adding a reference to the assembly Microsoft.Xrm.Sdk.Deployment.dll, which you can find in the SDK\bin folder. Alternatively, you can add the following service reference to your solution.

http://myservername/xrmdeployment/2011/deployment.svc

svcutil.exe http:// myservername/XRMDeployment/2011/Deployment.svc?wsdl

This will generate a configuration file and a code file that contains the client class. Add these two files to your client application and use the generated client class to call the service.

Deployment service installation

To execute calls against Microsoft Dynamics 365 deployment entities, the Deployment Service server role must be correctly installed on a Microsoft Dynamics 365 server. Make sure that the following criteria are met in your Deployment Service installation:

In order to use organization operations such as create or upgrade, you must install the Deployment Service server role using a domain user. The domain user account must have local admin and system admin rights on the SQL Server on which organization databases will be hosted.
The Deployment Service should be run with a different service identity than the other Microsoft Dynamics 365 services and application server. If you are using Network Service, the server role should be installed on a separate server by itself without any other Microsoft Dynamics 365 server roles installed. Installing the Deployment Service role alongside other server roles can cause security risks because both servers run under the Network Service account. If you use the Network service account you will not be able to perform organization operations using Windows PowerShell or the deployment web service.

For more information about installation of the deployment service, see the Microsoft Dynamics CRM server roles.

Microsoft Dynamics 365 has two primary server components: the Microsoft Dynamics 365 application server and the Microsoft Dynamics 365 Server. Each includes a separate group of server roles that are installed when Setup is run. The Deployment Service role is automatically installed when using the Setup wizard to install the Microsoft Dynamics 365 platform server.

Deployment service authentication and impersonation

Deployment Service authentication is handled through Active Directory, which is also known as Windows integrated authentication. You can also use impersonation, which enables you to call web service methods on behalf of another authenticated user to provide a desired feature or service. To call the deployment web service, you must be a Microsoft Dynamics 365 Deployment Administrator. For more information, see Add a deployment administrator.

The following sample shows how to use the ProxyClientHelper class to authenticate and use the deployment service using default credentials.

DeploymentServiceClient service = Microsoft.Xrm.Sdk.Deployment.Proxy.ProxyClientHelper.CreateClient(new Uri("http://MyServerName/XRMDeployment/2011/Deployment.svc"));
RetrieveAllRequest request = new RetrieveAllRequest()
{   
   EntityType = DeploymentEntityType.DefaultOrganization};   
   RetrieveAllResponse response = (RetrieveAllResponse) service.Execute(request);
}

Microsoft Dynamics 365 web services can be called by various clients and services on behalf of a Microsoft Dynamics 365 user. Every call must be an authenticated call. Impersonation is used to execute a call on behalf of an authenticated Microsoft Dynamics 365 user. When using impersonation, you avoid dealing with authentication and authorization issues in the web service (ASP.NET) code. Instead, you rely on Internet Information Services (IIS) to authenticate the user and pass an authenticated token to the web service. If the user cannot be authenticated, IIS passes an unauthenticated token.

The following sample shows how to use impersonation with the deployment service.

DeploymentServiceClient service = Microsoft.Xrm.Sdk.Deployment.Proxy.ProxyClientHelper.CreateClient(new Uri("http://myservername/XRMDeployment/2011/Deployment.svc"));
service.ClientCredentials.Windows.ClientCredential = new NetworkCredential("administrator", "myp@ssword!", "myservernamedom");
RetrieveAllRequest request = new RetrieveAllRequest() 
{   
   EntityType = DeploymentEntityType.DefaultOrganization};   
   RetrieveAllResponse response = (RetrieveAllResponse) service.Execute(request);
}

Deployment service capabilities

The deployment service follows a development model similar to the main Microsoft Dynamics 365 web service. There are entities, methods and messages that you use to interact with the deployment service. For more information about the main Microsoft Dynamics 365 web service, see Use Microsoft Dynamics 365 services in code.

There are two types of entities for the deployment service: deployment entities and deployment configuration settings. Both are accessed by the same set of methods. For more information about these entities, see Deployment entities and deployment configuration settings.

In addition to the core deployment entities, the deployment service provides the ability to read and edit advanced settings driven by metadata. These advanced settings provide access to information stored in the configuration database.

The deployment service supports both synchronous and asynchronous messages for the Execute method. For more information, see Deployment web service messages.

The following table lists the methods available in the deployment service.

Method name	Description
IDeploymentService.Delete	Deletes a record from a deployment entity.
IDeploymentService.Execute	Executes a request for the deployment service. For more information, see Deployment web service messages.
IDeploymentService.Retrieve	Retrieves a record from a deployment entity or deployment configuration settings.
IDeploymentService.RetrieveAll	Retrieves all records for a deployment entity or deployment configuration settings.
IDeploymentService.Update	Updates a record from a deployment entity or deployment configuration settings.

Share via

Introduction to the deployment web service

Add the deployment service to your project

Deployment service installation

Deployment service authentication and impersonation

Deployment service capabilities

See Also

Additional resources