Use connection strings in XRM tooling to connect to Microsoft Dataverse

With Dataverse, XRM tooling enables you to connect to your Dataverse environment by using connection strings. This is similar to the concept of connection strings used with SQL Server. Connection strings have native support in configuration files, including the ability to encrypt the configuration sections for maximum security. This enables you to configure Dataverse connections at deployment time, and not hard code in your application to connect to your Dataverse environment.

Create a connection string

You specify the connection string in the app.config or web.config file for your project, as shown in the following example.

<connectionStrings>  
    <add name="MyCDSServer" connectionString="AuthType=OAuth;[email protected];Password=passcode;Url=https://contosotest.crm.dynamics.com;AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;TokenCacheStorePath=c:\MyTokenCache;LoginPrompt=Auto"/>
</connectionStrings>  

After creating the connection string, you use it to create a CrmServiceClient object.

//Use the connection string named "MyCDSServer"  
//from the configuration file  
CrmServiceClient svc = new CrmServiceClient(ConnectionString);  

Alternately, you could use the ServiceClient class.

ServiceClient svc = new ServiceClient(ConnectionString);  

After creating a service client object, you can use the object to perform actions in Dataverse. More information: Use XRM Tooling to execute actions in Dataverse

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.

Connection string examples

The following examples show how you can use connection strings for connecting to online deployments and authentication scenarios. The connection string examples for on-premises and IFD deployment instances is now available in the Dynamics 365 Customer Engagement (on-premises) documentation at: Use connection strings in XRM tooling to connect

Named account using Office365

Create a new connection to Dataverse using a UserName or Password via Office365.

<add name="MyCDSServer" 
 connectionString="
  AuthType=Office365;
  [email protected]; 
  Password=passcode;
  Url=https://contoso.crm.dynamics.com"/>  

OAuth using named account in Microsoft 365 with UX to prompt for authentication

Create a new connection to Dataverse using a UserID or Password via OAuth.

<add name="MyCDSServer"
 connectionString="
  AuthType=OAuth;
  [email protected];
  Password=passcode;
  Url=https://contosotest.crm.dynamics.com;
  AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache;
  LoginPrompt=Auto"/>  

OAuth using current logged in user with fall back UX to prompt for authentication

Create a new connection to Dataverse using the current logged in user via OAuth.

<add name="MyCDSServer"
 connectionString="
  AuthType=OAuth;
  [email protected];
  Integrated Security=true;
  Url=https://contosotest.crm.dynamics.com;
  AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache\msal_cache.data;
  LoginPrompt=Auto"/>  

Certificate based authentication

Create a new connection to Dataverse using a Application or Client Id and a Certificate.

<add name="MyCDSServer" 
  connectionString="
  AuthType=Certificate;
  url=https://contosotest.crm.dynamics.com;
  thumbprint={CertThumbPrintId};
  ClientId={AppId};"
  />

ClientId or Client Secret based authentication

Create a new connection to Dataverse using a Application or Client Id and a Client Secret.

<add name="MyCDSServer" 
  connectionString="
  AuthType=ClientSecret;
  url=https://contosotest.crm.dynamics.com;
  ClientId={AppId};
  ClientSecret={ClientSecret}"
  />

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.

See also

Build Windows client applications using the XRM tools
Use CrmServiceClient constructors to connect to Dataverse
Use XRM Tooling to execute actions in Dataverse
CrmServiceClient