Utiliser les chaînes de connexion des outils XRM pour se connecter à Microsoft Dataverse

Les outils XRM vous permettent de vous connecter à votre environnement Dataverse à l’aide de chaînes de connexion. Cette approche est similaire au concept de chaînes de connexion utilisées avec SQL Server. Les fichiers de configuration prennent en charge en mode natif les chaînes de connexion, notamment la possibilité de chiffrer les sections de configuration pour une sécurité maximale. Cette fonctionnalité vous permet de configurer des connexions Dataverse au moment du déploiement et de ne pas les coder en dur dans votre application.

Lisez les informations importantes suivantes sur l’utilisation d’une chaîne de connexion dans le code d’application.

Important

Microsoft vous recommande d’utiliser le flux d’authentification le plus sécurisé disponible. Le flux d’authentification décrit dans cet article nécessite un très haut degré de confiance dans l’application et comporte des risques qui ne sont pas présents dans d’autres flux. Vous ne devez utiliser ce flux que lorsque d’autres flux plus sécurisés, tels que les identités managées, ne sont pas viables.

Créer une chaîne de connexion

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="MyCDSServer" connectionString="AuthType=OAuth;Username=jsmith@contoso.onmicrosoft.com;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>

Important

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

Après avoir créé la chaîne de connexion, utilisez-la pour créer un CrmServiceClient objet.

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

Vous pouvez également utiliser la ServiceClient classe.

ServiceClient svc = new ServiceClient(ConnectionString);

Note

Pour accéder à la chaîne de connexion dans votre code, incluez la directive suivante using pour référencer l’espace System.Configuration de noms : using System.Configuration;

Après avoir créé un objet client de service, utilisez l’objet pour effectuer des actions dans Dataverse. Pour plus d’informations, consultez Utiliser les outils XRM pour exécuter des actions dans Dataverse.

Paramètres de la chaîne de connexion

La chaîne de connexion contient une série de paires name=value séparées par des points-virgules. Le tableau suivant répertorie les paramètres pris en charge, que vous pouvez entrer dans n’importe quel ordre.

Nom du paramètre Description
ServiceUri, Service Uri, Url, ou Server Précise l’URL vers l’environnement Dataverse. 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 https://<organization-name>.crm.dynamics.com

Le nom d’organisation est nécessaire.
UserName, User Name, UserId, ou User Id Spécifie le nom 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 à l’environnement Dataverse. Les valeurs valides vont : AD, IFD (AD FS activé), OAuth, Certificate, ClientSecret ou Office365. Toutefois, seuls OAuth, Certificate, ClientSecret et Office365 sont les seules valeurs autorisées pour les environnements Dataverse.

REMARQUE : Office365 le type d’authentification est déconseillé et nous vous recommandons d’utiliser OAuth comme type d’authentification préféré. Pour plus d’informations, consultez Que dois-je faire pour corriger mon code d’application s’il est affecté ?
RequireNewInstance Spécifie s’il faut réutiliser une connexion existante en cas de rappel lorsque la connexion est toujours active. Si la valeur est définie true, le système crée une connexion unique. Si la valeur est définie false, la connexion existante peut être réutilisée.
ClientId, AppId ou ApplicationId Spécifie la valeur ClientID attribuée lorsque vous avez enregistré votre application dans Microsoft Entra ID ou Active Directory Federation Services (AD FS).
ClientSecret ou Secret Nécessaire lorsque le type Auth est défini sur ClientSecret. Chaîne de clé secrète client à utiliser pour l’authentification.
RedirectUri ou ReplyUrl Spécifie l’URI de redirection de l’application que vous avez enregistrée dans Microsoft Entra ID 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 au processus de définir et de configurer ce chemin.

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é à entrer des informations d’identification si les informations d’identification ne sont pas fournies. Les valeurs valides sont :

- 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 vous utilisez une méthode de connexion qui n’a pas d’interface utilisateur, utilisez cette valeur.

Ce paramètre n’est applicable que lorsque le type d’authentification est spécifié en tant que OAuth.
StoreName ou CertificateStoreName Spécifie le nom du magasin où le certificat identifié par empreinte se trouve. Lorsqu'elle est définie, Thumbprint est requise.
Thumbprint ou CertThumbprint Spécifie l’empreinte du certificat à utiliser lors d’une connexion S2S. Lorsque AppID est défini, il est requis et les valeurs de UserID et Password sont ignorées.
Integrated Security Spécifie d’utiliser les informations d’identification Windows actuelles pour tenter de créer un jeton pour les instances. À partir de Microsoft.CrmSdk.XrmTooling.CoreAssembly version 9.1.0.21 de NuGet

Note

Lorsque vous utilisez l'AuthType\AuthenticationType OAuth
À des fins de développement et de prototypage, les URI AppId ou ClientId et Redirect suivants sont fournis pour une utilisation dans les flux OAuth.
Pour une utilisation en production, créez un AppId ou un ClientId spécifique à votre locataire dans le portail de gestion Azure.
Exemple d’AppId ou de ClientId = 51f81489-12ee-4a9e-aaae-a2591f45987d
Exemple de RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97

Exemples de chaîne de connexion

Les exemples ci-dessous montrent comment utiliser les chaînes de connexion pour se connecter aux déploiements et scénarios d’authentification en ligne. Pour obtenir des exemples de chaînes de connexion d’instances de déploiement locales et IFD, consultez Utiliser des chaînes de connexion dans les outils XRM pour se connecter.

Compte nommé utilisant Office365

Créez une nouvelle connexion à Dataverse en utilisant un nom d’utilisateur ou un mot de passe via Office365.

Note

Cet élément AuthType est obsolète. Utilisez OAuth comme type d’authentification préféré. Pour plus d’informations, consultez Authentifier à l’aide d’Office365.

<add name="MyCDSServer" 
 connectionString="
  AuthType=Office365;
  Username=jsmith@contoso.onmicrosoft.com; 
  Password=passcode;
  Url=https://contoso.crm.dynamics.com"/>

OAuth avec compte nommé dans Microsoft 365, avec incitation à l'authentification via l’expérience utilisateur

Créez une nouvelle connexion à Dataverse à l’aide d’un ID utilisateur ou d’un mot de passe via OAuth.

Note

OAuth est le type d’authentification préféré pour se connecter à Dataverse 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 Microsoft Entra ID et de l’authentification multifacteur.

<add name="MyCDSServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith@contoso.onmicrosoft.com;
  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 utilisant l’utilisateur actuellement connecté avec retour à l’UX pour inviter à s’authentifier

Créez une nouvelle connexion à Dataverse à l’aide de l’utilisateur actuellement connecté via OAuth.

Note

OAuth est le type d’authentification préféré pour se connecter à Dataverse 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 Microsoft Entra ID et de l’authentification multifacteur.

<add name="MyCDSServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith@contoso.onmicrosoft.com;
  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"/>

Authentification basée sur un certificat

Créez une connexion à Dataverse à l’aide d’une application ou d’un ID client et d’un certificat.

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

Authentification basée sur le ClientId ou la clé secrète client

Créez une connexion à Dataverse à l’aide d’une application ou d’un ID client et d’une clé secrète client.

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

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 réussit 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 à l’aide des outils XRM
Utilisation des constructeurs CrmServiceClient pour se connecter à Dataverse
Utiliser les outils XRM pour exécuter des actions dans Dataverse
CrmServiceClient

  • Last updated on