With Microsoft Dynamics CRM Online 2016 Update and Microsoft Dynamics CRM 2016 (on-premises), XRM tooling enables to connect to CRM instance by using connection strings. This is similar to the concept of connection strings used with Microsoft SQL Server. Connection strings have native support in configuration files, including the ability to encrypt the configuration sections for maximum security. This enables to configure CRM connections at deployment time, and not hard code in the application to connect to CRM instance.
Create a connection string
Specify the connection string in the app.config or web.config file for VS project, as shown in the following example.
XML
<connectionStrings>
<add name=”CRMServer” connectionString=”AuthType=AD;Url=http://amartestsrv:8080/Test;” /></connectionStrings>
After creating the connection string, use it to create a CrmServiceClient object.
C#
//Use the connection string named “CRMServer” from the configuration fileCrmServiceClient crmSvc = new CrmServiceClient(ConfigurationManager.ConnectionStrings[“MyCRMServer”].ConnectionString);
After creating a CrmServiceClient object, we can use the object to perform actions in CRM.
Connection string parameters
The connection string contains a series of name=value pair separated by semi-colons. The following table lists supported parameters, which can be entered in any order.
| Parameter Name | Description |
| ServiceUri, Service Uri, Url, or Server | Specifies the URL to the Microsoft Dynamics CRM Server. The URL can use http or https protocol, and the port is optional. The default port is 80 for the http protocol and 443 for the https protocol. The server URL is typically in the format of http://crm-server:port/organization-name for CRM on-premises and https://organization-name. crm.dynamics.com for CRM Online.
The organization name is required. You can specify either the friendly or the unique name of the organization to connect to. Example: http://amartestsrv/test, http://amartestsrv:5555/test, https://amartestsrv/test, https://test.crmhunt.com:444. |
| Domain | Specifies the domain that will verify user credentials. |
| UserName, User Name, UserId, or User Id | Specifies the user’s identification name associated with the credentials. |
| Password | Specifies the password for the user name associated with the credentials. |
| HomeRealmUri or Home Realm Uri | Specifies the Home Realm Uri. |
| AuthenticationType or AuthType | Specifies the authentication type to connect to CRM instance. Valid values are: AD, IFD (AD FS enabled), OAuth, or Office365.
Office365 is permitted for CRM Online instances only. |
| RequireNewInstance | Specifies whether to force the creation of a new instance when the connection is created. Possible values are True or False. |
| ClientId, AppId or ApplicationId | Specifies the ClientID assigned when you registered your application in Microsoft Azure Active Directory or Active Directory Federation Services (AD FS).
This parameter is applicable only when the authentication type is specified as OAuth. |
| RedirectUri or ReplyUrl | Specifies the redirect URI of the application you registered in Microsoft Azure Active Directory or Active Directory Federation Services (AD FS).
This parameter is applicable only when the authentication type is specified as OAuth. |
| TokenCacheStorePath | Specifies the full path to the location where the user token cache should be stored. The running process should have access to the specified path. It is the processes responsibility to set and configure this path.
This parameter is applicable only when the authentication type is specified as OAuth. |
| LoginPrompt | Specifies whether the user is prompted for credentials if the credentials are not supplied. Valid values are:
This parameter is applicable only when the authentication type is specified as OAuth. |
Connection string examples
The following examples show how we can use connection strings for connecting to different deployments and authentication scenarios.
Integrated on-premises authentication
<add name=”CRMServer” connectionString=”AuthType=AD;Url=http://amartestsrv:8080/Test;” />
Named account using on-premises authentication
<add name=”CRMServer” connectionString=”AuthType=AD;Url=http://amartestsrv:8080/Test; Domain=crmhunt; Username=admin; Password=pass#123$” />
Named account using Office 365
<add name=”CRMServer” connectionString=”AuthType=Office365; Username= [email protected]; Password=pass#123$;Url=https://crmhunt.crm.dynamics.com”/>
OAuth using named account in Office 365 with UX to prompt for authentication
<add name=”CRMServer” connectionString=”AuthType=OAuth; Username= [email protected]; Password=pass#123$; Url=https://crmhunttest.crm.dynamics.com; AppId=<GUID>;RedirectUri =app://<GUID>;TokenCacheStorePath =c:\MyTokenCache; LoginPrompt=Auto”/>
OAuth using named account in CRM on-premises with UX to prompt for authentication
<add name=”CRMServer” connectionString=”AuthType=OAuth;Username= [email protected]; Password=pass#123$;Url=https://amartestsrv:8080/Test; AppId=<GUID>; RedirectUri=app://<GUID>;TokenCacheStorePath =c:\MyTokenCache; LoginPrompt=Auto”/>
IFD using a named account with delegation to a sub realm
<add name=”CRMServer” connectionString=”AuthType=IFD;Url=http://amartestsrv:8080/Test; HomeRealmUri=https://amartestsrv.server.com/adfs/services/trust/mex/;Domain=crmhunt; Username=admin; Password=pass#123$” />
Determine your connection status
To determine if the connection request was successful, check the value of the CrmServiceClient.IsReady property. If true, the connection is successful, and you are ready to work. Otherwise, check the values of the CrmServiceClient.LastCrmError and CrmServiceClient.LastCrmException properties for the cause of the connection failure.
Pingback: Use Connection strings in XRM tooling to connect to CRM - Microsoft Dynamics CRM Community