Simplified connection to Microsoft Dynamics CRM 2013

 

Applies To: Dynamics CRM 2013

Developer Extensions for Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online uses the concept of a connection string to connect to the Microsoft Dynamics CRM server. This is similar to the concept of connection strings used with Microsoft SQL Server. Connection strings are a natural part of the ADO.NET framework and also have native support in configuration files, including the ability to encrypt the configuration sections for maximum security. This encourages you to use a robust model in which Microsoft Dynamics CRM connections are configured at deployment time, and aren’t hard coded in your application. As such, all APIs in Developer Extensions for Microsoft Dynamics CRM work with a CrmConnection object, used internally by the CrmOrganizationServiceContext class as shown in this topic, which uses a connection string to connect to the server.

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

<connectionStrings>
  <add name="Crm" connectionString="Url=http://crm.contoso.com/xrmContoso;"/>
</connectionStrings>

Security Note
If you add any sensitive information to the app.config or web.config file, for example an account password, be sure to take appropriate security precautions to protect the information.

In This Topic

Create a connection string

Connection string parameters

Connection string examples

Create a connection string

The connection string is used to instantiate a CrmConnection object, which in turn can be used to instantiate an OrganizationService object or a CrmOrganizationServiceContext object.

//Use the Microsoft Dynamics CRM Online connection string from the app.config file named "CRMOnline".
var connection = new CrmConnection("CRMOnline");
var service = new OrganizationService(connection);
var context = new CrmOrganizationServiceContext(connection);

A CrmConnection can also be created independently of the app.config file and constructed inline as follows.

var connection = CrmConnection.Parse("Url=http://crm.contoso.com/xrmContoso; Domain=CONTOSO; Username=jsmith; Password=passcode;");

Connection string parameters

The basic format of the connection string is the same as an OLEDB connection string. It’s a series of name/value pairs separated by semicolons. The following table lists supported parameters, which can be entered in any order.

Parameter name	Description
Server, Url, or Service Uri	Specifies the URL to the Microsoft Dynamics CRM server. The URL can be http or https and the port is optional if it is http over port 80 or https over port 443. The server URL is typically in the format of http:// crm-server: port/organization-name or for Microsoft Dynamics CRM Online  https:// organization-name.crm.dynamics.com. The organization name is required.
Domain	Specifies the domain that will verify user credentials.
Username 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.
Device ID or Device User Name	Specifies the user-defined Windows Live Services Device ID. It can be any non-empty string. This device ID will be registered with the device password the first time an authentication is run. If the device ID and password don’t match the previously registered values, the authentication will fail.
Device Password	Specifies the user-defined Windows Live Services Device password. It must be at least six characters in length. This password will be registered with the device ID the first time an authentication is run. If the device ID and password don’t match the previously registerd values, the authentication will fail.
Timeout	Gets passed to the Timeout property of the OrganizationServiceProxy class.
Home Realm Uri	Gets passed to the HomeRealmUri property of the OrganizationServiceProxy class.
Proxy Types Enabled	True by default, this parameter enables the OrganizationService to return proxy types instead of just the base Entity type.
Proxy Types Assembly	Specifies the assembly that contains the proxy types from Microsoft Dynamics CRM, generated using the CrmSvcUtil.exe tool, with the Microsoft.Xrm.Client.CodeGeneration extension.
Caller ID	Gets passed to the CallerId property of the OrganizationServiceProxy class.
Service Configuration Instance Mode	Can be set to Static, PerName, PerRequest, or PerInstance. PerName is default; this optimizes the number of times an IServiceConfiguration<TService> will be created for an OrganizationService, so that only one is created for each connection string. For more information about other possible values, see Specify the instanceMode attribute.
User Token Expiry Window	Specifies a TimeSpan, formatted hh:mm:ss, used as an offset for when a new user token is retrieved. For example, if this parameter is set to "00:10:00", a new user token will be retrieved 10 minutes before the token actually expires.

Connection string examples

The following example shows the connection string using integrated on-premises authentication.

Url=http://crm.contoso.com/xrmContoso;

The following example shows the connection string using Active Directory authentication.

Url=http://crm.contoso.com/xrmContoso; Domain=CONTOSO; Username=jsmith; Password=passcode

The following example shows the connection string using Microsoft account to connect to Microsoft Dynamics CRM Online…

Url=https://contoso.crm.dynamics.com; Username=jsmith@live-int.com; Password=passcode; DeviceID=contoso-ba9f6b7b2e6d; DevicePassword=passcode

The following example shows the connection string using Microsoft Online Services to connect to Microsoft Dynamics CRM Online.

Url=https://contoso.crm.dynamics.com; Username=jsmith@contoso.onmicrosoft.com; Password=passcode; 

See Also

Sample: Simplified connection quick start using Microsoft Dynamics CRM 2013
Developer extensions for Microsoft Dynamics CRM 2013
Generate code with the code generation tool extensions (Dynamics CRM 2013)
Portal walkthroughs (Dynamics CRM 2013)