Use CrmServiceClient constructors to connect to Dynamics 365

 

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

To connect to Microsoft Dynamics 365, you create an instance of the CrmServiceClient class, and then use one of the constructors to connect. All the calls to Dynamics 365 using the CrmServiceClient class are thread safe.

Apart from the constructors mentioned in this topic, you can also use connection strings with CrmServiceClient to connect to Dynamics 365. More information: Use connection strings in XRM tooling to connect to Dynamics 365

In this topic

Connect to Dynamics 365 using OrganizationServiceProxy

Connect to Dynamics 365 using OrganizationWebProxyClient

Connect to Dynamics 365 (online) (Office 365)

Connect to Dynamics 365 (online) (Office 365) using OAuth

Connect to Dynamics 365 on-premises (Active Directory)

Connect to Dynamics 365 Internet-facing deployment (IFD)

Connect to Dynamics 365 Internet-facing deployment (IFD) using OAuth

Connect to Dynamics 365 (claims-based)

Determine your connection status

Connect to Dynamics 365 using OrganizationServiceProxy

Use the following constructor to connect to Dynamics 365 using the user-provided OrganizationServiceProxy instance.

CrmServiceClient crmSvc = new CrmServiceClient(<orgServiceProxy>);

Connect to Dynamics 365 using OrganizationWebProxyClient

Use the following constructor to connect to Dynamics 365 using the user-provided OrganizationWebProxyClient instance. This constructor is introduced in Microsoft Dynamics 365 (online & on-premises).

CrmServiceClient crmSvc = new CrmServiceClient(<orgWebProxyClient>);

Connect to Dynamics 365 (online) (Office 365)

Use the following constructor to connect to your Dynamics 365 (online) instance in Office 365.

CrmServiceClient crmSvc = new CrmServiceClient("<UserName>", CrmServiceClient.MakeSecureString("<Password>"), "<CrmRegion>", "<OrgName>", useUniqueInstance:false, useSsl:false, <orgDetail>, isOffice365:true);

Valid values for the <CrmRegion> parameter are: NorthAmerica, EMEA, APAC, SouthAmerica, Oceania, JPN, CAN, IND, and NorthAmerica2. If you set this to String.Empty, it will search servers in all the regions for the Dynamics 365 organization. For the <OrgName> parameter, you can specify either the unique or friendly name.

The following parameters are optional: useUniqueInstance, useSsl, and orgDetail.

Connect to Dynamics 365 (online) (Office 365) using OAuth

Use the following constructor to use OAuth protocol to connect to your Dynamics 365 (online) instance in Office 365. The OAuth support is introduced in Microsoft Dynamics 365 (online & on-premises).

CrmServiceClient crmSvc = new CrmServiceClient("<UserName>", CrmServiceClient.MakeSecureString("<Password>"), "<CrmRegion>", "<OrgName>", useUniqueInstance:false, <orgDetail>,
                  <userIdentifier>, <clientId>, <redirectUri>, <tokenCachePath>, <externalOrgWebProxyClient>, PromptBehavior.Auto);

This constructor uses Microsoft Azure Active Directory Authentication Library (ADAL) to authenticate users. If the user credentials (user name and password) aren’t specified, ADAL prompts the user to provide the credentials depending on the PromptBehavior parameter (optional) specified in the constructor. ADAL authenticates the credentials using the OAuth protocol, obtains the access and refresh tokens from Azure Active Directory, and then uses the access token to make requests to Dynamics 365.

Valid values for the <CrmRegion> parameter are: NorthAmerica, EMEA, APAC, SouthAmerica, Oceania, JPN, CAN, IND, and NorthAmerica2. If you set this to String.Empty, it will search servers in all the regions for the Dynamics 365 organization. For the <OrgName> parameter, you can specify either the unique or friendly name.

Connect to Dynamics 365 on-premises (Active Directory)

Use the following constructor to connect to an on-premises instance with Active Directory authentication.

CrmServiceClient crmSvc = new CrmServiceClient(new System.Net.NetworkCredential("<UserName>", "<Password>", “<Domain>”), AuthenticationType.AD, "<Server>", "<Port>", "<OrgName>", useUniqueInstance:false, useSsl:false, <orgDetail>);

This will run an Active Directory authentication based on the specified domain. For the <Server> parameter, specify the host name of your Dynamics 365 server, for example: crmtest. For the <OrgName> parameter, you can specify either the unique or friendly name.

The following parameters are optional: useUniqueInstance, useSsl, and orgDetail.

Connect to Dynamics 365 Internet-facing deployment (IFD)

Use the following constructor to connect to a Dynamics 365 IFD instance.

CrmServiceClient crmSvc = new CrmServiceClient(new System.Net.NetworkCredential("<UserName>", "<Password>", “<Domain>”), AuthenticationType.IFD, "<Server>", "<Port>", "<OrgName>", useUniqueInstance:false, useSsl:false, <orgDetail>);

This will run a claims-based authentication based on the specified local domain. This is useful for customers that use AD FS, and have configured their Dynamics 365 server as claims, where the user population lives in the same AD FS domain as the Dynamics 365 server. For the <Server> parameter, specify the host name of your Dynamics 365 server, for example, crmtest. For the <OrgName> parameter, you can specify either the unique or friendly name.

The following parameters are optional: useUniqueInstance, useSsl, and orgDetail.

Connect to Dynamics 365 Internet-facing deployment (IFD) using OAuth

Use the following constructor to use the OAuth protocol in Active Directory Federation Services (AD FS) in Windows Server 2012 R2 to connect to a Dynamics 365 IFD instance. For this constructor to work, the computer where Microsoft Dynamics 365 Server is installed must have been configured to use AD FS 2.2 as the security token service (STS). The OAuth support for connecting to a Dynamics 365 IFD instance is introduced in Dynamics 365.

CrmServiceClient crmSvc = new CrmServiceClient("<UserName>", CrmServiceClient.MakeSecureString("<Password>"), "<HomeRealm>", "<HostName>", "<Port>", "<OrgName>", useSsl:true, useUniqueInstance:false, 
                        <orgDetail>, <userIdentifier>, <clientId>, <redirectUri>, <tokenCachePath>, externalOrgWebProxyClient, PromptBehavior.Auto);

The clientId and redirectUri values for the application supporting OAuth should be registered in the IFD server.

If the user credentials (user name and password) aren’t specified, ADAL prompts the user to provide the credentials depending on the PromptBehavior parameter (optional) specified in the constructor. ADAL authenticates the user using the security token from AD FS, and uses the token to perform actions in Dynamics 365.

Connect to Dynamics 365 (claims-based)

Use the following constructor to use claims-based authentication.

CrmServiceClient crmSvc = new CrmServiceClient(new System.Net.NetworkCredential("<UserName>", "<Password>", “<Domain>”, "<HomeRealm>"),"<Server>", "<Port>", "<OrgName>");

This will run a claims-based authentication against the specified Home realm. This is useful for customers that use AD FS, and have configured their Dynamics 365 server as claims, where the user population lives in the same AD FS domain as the Dynamics 365 server. For the <Server> parameter, specify the host name of your Dynamics 365 server, for example, crmtest. For the <OrgName> parameter, you can specify either the unique or friendly name.

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

AuthenticationType
Use connection strings in XRM tooling to connect to Dynamics 365
Use PowerShell cmdlets for XRM tooling to connect to Dynamics 365
Use XRM tooling to execute actions in Dynamics 365
Sample: Quick start for Microsoft Dynamics 365
Build Windows client applications using the XRM tools

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright