Utilisation de chaînes de connexion dans l’outillage XRM

Avec Dynamics 365 Customer Engagement (on-premises), les outils XRM vous permettent de vous connecter à votre instance à l’aide de chaînes de connexion. Ceci est similaire au concept des chaînes de connexion utilisées avec SQL Server. Les chaînes de connexion assurent une prise en charge native dans les fichiers de configuration, notamment la capacité d’encoder les sections de configuration pour un maximum de sécurité. Cela vous permet de configurer les connexions Dynamics 365 Customer Engagement (locales) au moment du déploiement, et non de coder en dur dans votre application pour vous connecter à votre instance.

Remarque

La documentation sur les chaînes de connexion applicable aux utilisateurs de Dataverse est désormais disponible dans la documentation Power Apps à l’adresse suivante : Utiliser des chaînes de connexion dans les outils XRM pour se connecter à Dataverse

Créer une chaîne de connexion

Vous spécifiez la chaîne de connexion dans le fichier App.config ou web.config de votre projet, comme illustré dans l’exemple suivant.

<connectionStrings>  
    <add name="MyCRMServer" connectionString="AuthType=AD;Url=https://contoso:8080/Test;" />  
</connectionStrings>

Important

Si vous ajoutez des informations sensibles au app.config fichier ou web.config , par exemple un mot de passe de compte, assurez-vous de prendre les précautions de sécurité appropriées pour protéger ces informations.

Après avoir créé la chaîne de connexion, vous devez l’utiliser pour créer un objet CrmServiceClient.

//Use the pre-configured connection string named "MyCRMServer"
CrmServiceClient crmSvc = new CrmServiceClient(ConfigurationManager.ConnectionStrings["MyCRMServer"].ConnectionString);

Remarque

Vous devrez utiliser la directive suivante using dans votre code pour référencer l’espace System.Configuration de noms afin d’accéder à la chaîne de connexion dans votre code : using System.Configuration;

Après avoir créé un CrmServiceClient objet, vous pouvez l’utiliser pour effectuer des actions dans Dynamics 365 Customer Engagement (local). Pour plus d’informations : Utiliser l’outil XRM pour exécuter des actions

Paramètres de la chaîne de connexion

La chaîne de connexion contient une série de paires nom=valeur séparées par des points-virgules. Le tableau suivant répertorie les paramètres pris en charge. Ils peuvent être saisis dans n'importe quel ordre.

Nom du paramètre Descriptif
ServiceUri, Service Uri, Urlou Server Spécifie l’URL du serveur Dynamics 365. L’URL peut utiliser le protocole http ou https, et le port est facultatif. Le port par défaut est 80 pour le protocole http et 443 pour le protocole https. L’URL du serveur est généralement au format de https://crm-server:port/organization-name Dynamics 365 Customer Engagement (local).

Le nom d’organisation est nécessaire. Vous pouvez spécifier le nom convivial ou le nom unique de l’organisation à laquelle vous souhaitez vous connecter.

Exemple : https://contoso/test, https://contoso:5555/test, https://contoso/test, ou https://10.10.10.2/test.
Domain Spécifie le domaine qui vérifiera les informations d’identification de l’utilisateur.
UserName, User Name, UserIdou User Id Spécifie le nom de l’ID d’utilisateur associé aux informations d’identification.
Password Spécifie le mot de passe d’utilisateur associé aux informations d’identification.
HomeRealmUri ou Home Realm Uri Spécifie l’URI du domaine d’accueil.
AuthenticationType ou AuthType Spécifie le type d’authentification pour se connecter à Dynamics 365 Customer Engagement (sur site). Les valeurs valides sont : AD, IFD (AD FS activé), OAuth, ou Office365.

- AD et IFD sont autorisés pour les instances Dynamics 365 Customer Engagement (locales) uniquement.
- OAuthest autorisé pour les instances Dynamics 365 Customer Engagement (sur site) et Dataverse. Pour la version « on-premises », l’inscription à ADFS 3.x+ et à App\Client Id avec ADFS est obligatoire pour le type OAuth.
- Office365 n’est autorisé que pour les instances Dataverse.
- L’utilisation d’un certificat ou d’une clé secrète client pour l’authentification est prise en charge dans Dataverse, mais pas dans Dynamics 365 Customer Engagement (local).
RequireNewInstance Spécifie s’il faut réutiliser une connexion existante en cas de rappel lorsque la connexion est toujours active. La valeur par défaut indique false que la connexion existante doit être réutilisée. Si la valeur est true, le système sera contraint de créer une connexion unique.
ClientId, AppId ou ApplicationId Spécifie l’attribué ClientID lorsque vous avez inscrit votre application dans Azure Active Directory ou Active Directory Federation Services (AD FS).
RedirectUri ou ReplyUrl Spécifie l’URI de redirection de l’application que vous avez inscrite dans Azure Active Directory ou Active Directory Federation Services (AD FS).

Ce paramètre n’est applicable que lorsque le type d’authentification est spécifié en tant que OAuth.
TokenCacheStorePath Spécifie le chemin d’accès complet à l’emplacement où le cache de jeton de l’utilisateur doit être stocké. Le processus d’exécution doit avoir accès au chemin d’accès spécifié. Il incombe aux processus de définir et de configurer ce chemin d’accès.

Ce paramètre n’est applicable que lorsque le type d’authentification est spécifié en tant que OAuth.
LoginPrompt Spécifie si l’utilisateur est invité à fournir les informations d’identification si elles ne sont pas fournies. Les valeurs valides sont les suivantes :

- Always : invite toujours l’utilisateur à spécifier les informations d’identification.
- Auto : permet à l’utilisateur de choisir si l’invite doit être affichée ou non dans l’interface de contrôle de la connexion.
- Never : n’invite pas l’utilisateur à spécifier les informations d’identification. Si l’utilisation d’une méthode de connexion ne dispose pas d’une interface utilisateur, vous devez utiliser cette valeur.

Ce paramètre n’est applicable que lorsque le type d’authentification est spécifié en tant que OAuth.
SkipDiscovery Spécifie s’il faut appeler la découverte d’instance pour déterminer l’URI de connexion d’une instance donnée. À partir de la version NuGet Microsoft.CrmSdk.XrmTooling.CoreAssembly version 9.0.2.7, valeur par défaut = true. Les anciennes versions sont définies par défaut sur false.
Remarque : Si la valeur est true, il est important que l'utilisateur fournisse l'URI correct et précis pour l'instance cible.
Thumbprint ou CertificateThumbprint Spécifie l’empreinte du certificat à utiliser lors d’une connexion S2S. Une fois défini, l’AppID est requis et les valeurs ID utilisateur et Mot de passe sont ignorées.
StoreName ou CertificateStoreName Spécifie le nom du magasin où le certificat identifié par empreinte se trouve. Une fois défini, l’empreinte est requise.

Remarque

Lors de l’utilisation du type d’authentification OAuth à des fins de développement et de prototypage, nous avons fourni l’AppId ou le ClientId et l’URI de redirection suivants à utiliser dans les flux OAuth. Nous les utilisons dans tous nos exemples de code.

Exemple d’AppId ou ClientId = 00001111-aaaa-2222-bbbb-3333cccc4444
Exemple de RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97

Pour une utilisation de production, vous devez créer un AppId ou un ClientId spécifiques à votre client dans le Portail de gestion Azure.

Exemples de chaîne de connexion

Les exemples suivants montrent comment vous pouvez utiliser des chaînes de connexion pour vous connecter à Dynamics 365 Customer Engagement (on-premises) et aux déploiements IFD. Les exemples de chaînes de connexion pour les instances Dataverse sont désormais disponibles dans la documentation Power Apps à l’adresse suivante : Utiliser des chaînes de connexion dans les outils XRM pour se connecter à Dataverse

Authentification intégrée sur site

<add name="MyCRMServer"
connectionString="AuthType=AD;
Url=https://contoso:8080/Test;" />

Compte nommé utilisant l’authentification locale

<add name="MyCRMServer"
connectionString="AuthType=AD;
Url=https://contoso:8080/Test;
Domain=CONTOSO;
Username=jsmith;
Password=passcode" />

OAuth à l’aide d’un compte nommé dans Dynamics 365 Customer Engagement (on-premises) avec interface utilisateur (UI) pour solliciter l’authentification

Créez une nouvelle connexion à l’aide d’un nom d’utilisateur ou d’un mot de passe via oAuth.

Remarque

OAuth est le type d’authentification préféré pour la connexion à Dynamics 365 Customer Engagement (sur site) lors de l’utilisation d’un flux interactif. Ce type d’authentification prend entièrement en charge les fonctionnalités de l’accès conditionnel Azure Active Directory et de l’authentification multifacteur.

<add name="MyCRMServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith;
  Password=passcode;
  Url=https://contoso:8080/Test;
  AppId=00001111-aaaa-2222-bbbb-3333cccc4444;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache;
  LoginPrompt=Auto"/>

OAuth utilisant l’utilisateur actuellement connecté avec retour à l’UX pour inviter à s’authentifier

Créez une nouvelle connexion en utilisant l’utilisateur actuellement connecté via oAuth.

Remarque

OAuth est le type d’authentification préféré pour la connexion à Dynamics 365 Customer Engagement (sur site) lors de l’utilisation d’un flux interactif. Ce type d’authentification prend entièrement en charge les fonctionnalités de l’accès conditionnel Azure Active Directory et de l’authentification multifacteur. Pour en savoir plus sur le Integrated Security paramètre, consultez le sujet ici.

<add name="MyCRMServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith;
  Integrated Security=true;
  Url=https://contoso:8080/Test;
  AppId=00001111-aaaa-2222-bbbb-3333cccc4444;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache;
  LoginPrompt=Auto"/>

IFD utilisant un compte nommé avec la délégation à un sous-domaine

<add name="MyCRMServer"
connectionString="AuthType=IFD;Url=https://contoso:8080/Test;
 HomeRealmUri=https://server-1.server.com/adfs/services/trust/mex/;
Domain=CONTOSO; 
Username=jsmith; 
Password=passcode" />

Déterminer l’état de votre connexion

Pour déterminer si la demande de connexion a été réussie, vérifiez la valeur de la propriété CrmServiceClient.IsReady Si la valeur est true, la connexion est réussie et vous êtes prêt à travailler. Sinon, vérifiez les valeurs des propriétés CrmServiceClient .LastCrmError et CrmServiceClient .LastCrmException de la cause de l’échec de la connexion.

Voir aussi

Créer des applications clientes Windows avec les outils XRM
Utiliser les constructeurs CrmServiceClient pour se connecter à Dynamics 365 Customer Engagement (local) et Dataverse
Utiliser l’outil XRM pour exécuter des actions
CrmServiceClient

  • Last updated on