Usar cadenas de conexión en las herramientas de XRM para conectarse a Microsoft Dataverse

Las herramientas XRM permiten conectarse al entorno de Dataverse mediante cadenas de conexión. Este enfoque es similar al concepto de cadenas de conexión usadas con SQL Server. Los archivos de configuración admiten de forma nativa cadenas de conexión, incluida la capacidad de cifrar las secciones de configuración para lograr la máxima seguridad. Esta característica le permite configurar conexiones de Dataverse en tiempo de implementación y no codificarlas de forma rígida en la aplicación.

Lea la siguiente información importante sobre el uso de una cadena de conexión en el código de la aplicación.

Importante

Microsoft recomienda utilizar el flujo de autenticación más seguro disponible. El flujo de autenticación descrito en este artículo requiere un alto grado de confianza en la aplicación y conlleva riesgos que no están presentes en otros flujos. Solo debe usar este flujo cuando otros flujos más seguros, como las identidades administradas, no sean viables.

Crear una cadena de conexión

Especifique la cadena de conexión en el app.config archivo o web.config del proyecto, como se muestra en el ejemplo siguiente.

<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>

Importante

Si agrega información confidencial a app.config o web.config file, como una contraseña de cuenta, tome las precauciones de seguridad adecuadas para proteger la información.

Después de crear la cadena de conexión, úsela para crear un CrmServiceClient objeto .

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

Como alternativa, puede usar la ServiceClient clase .

ServiceClient svc = new ServiceClient(ConnectionString);

Nota

Para acceder a la cadena de conexión en su código, incluya la siguiente using directiva para hacer referencia al System.Configuration espacio de nombres: using System.Configuration;

Después de crear un objeto de cliente de servicio, use el objeto para realizar acciones en Dataverse. Para obtener más información, consulte Uso de herramientas XRM para ejecutar acciones en Dataverse.

Parámetros de la cadena de conexión

La cadena de conexión contiene una serie de pares nombre=valor separados por punto y coma. En la tabla siguiente se enumeran los parámetros admitidos, que puede especificar en cualquier orden.

Nombre de parámetro Descripción
ServiceUri, Service Uri, Url o Server Especifica la dirección URL al entorno de Dataverse. La URL puede utilizar el protocolo http o https, y el puerto es opcional. El puerto predeterminado es 80 para el protocolo http y 443 para el protocolo https. La dirección URL del servidor suele encontrarse en el formato https://<organization-name>.crm.dynamics.com

Se requiere el nombre de la organización.
UserName, User Name, UserId o User Id Especifica el nombre de identificación del usuario asociado con las credenciales.
Password Especifica la contraseña del nombre de usuario asociado con las credenciales.
HomeRealmUri o Home Realm Uri Especifica el URI de dominio de inicio
AuthenticationType o AuthType Especifica el tipo de autenticación para conectarse al entorno de Dataverse. Los valores válidos son: AD, IFD (AD FS habilitado), OAuth, Certificate, ClientSecret u Office365. Sin embargo, solo se permiten los valores OAuth, Certificate, ClientSecret y Office365 para entornos de Dataverse.

NOTA: Office365 el tipo de autenticación está en desuso y se recomienda usar OAuth como tipo de autenticación preferido. Para obtener más información, consulte ¿Qué debo hacer para corregir mi código de aplicación si se ve afectado?
RequireNewInstance es-ES: Indica si se debe reutilizar una conexión existente si se invoca nuevamente mientras la conexión sigue activa. Si se establece en true, el sistema crea una conexión única. Si se establece en false, se puede reutilizar la conexión existente.
ClientId, AppId o ApplicationId Especifica el ClientID asignado cuando se registró su aplicación en Microsoft Entra ID o Servicios de federación de Active Directory (AD FS).
ClientSecret o Secret Necesario cuando Tipo de autenticación se establece en ClientSecret. Cadena secreta de cliente para utilizar en la autenticación.
RedirectUri o ReplyUrl Especifica el URI de redirección de la aplicación que registró en Microsoft Entra ID o Servicios de federación de Active Directory (AD FS).

Este parámetro es aplicable solo cuando especifica el tipo de autenticación como OAuth.
TokenCacheStorePath Especifica la ruta de acceso completa a la ubicación donde la memoria caché del símbolo de usuario debe ser almacenada. El proceso en ejecución debe tener acceso a la ruta especificada. Es responsabilidad del proceso establecer y configurar esta ruta de acceso.

Este parámetro es aplicable solo cuando especifica el tipo de autenticación como OAuth.
LoginPrompt Especifica si se solicita al usuario credenciales si no se proporcionan las credenciales. Los valores válidos son:

- Always: Pide siempre al usuario que especifique credenciales.
- Auto: Permite que el usuario seleccione en la interfaz de control de inicio de sesión si se muestra un mensaje o no.
- Never: no solicita al usuario que especifique las credenciales. Si usa un método de conexión que no tiene una interfaz de usuario, use este valor.

Este parámetro es aplicable solo cuando especifica el tipo de autenticación como OAuth.
StoreName o CertificateStoreName Especifica el nombre del almacén donde el certificado identificado por huella digital se encuentra. Cuando se establece, Thumbprint es necesario.
Thumbprint o CertThumbprint Especifica la huella digital del certificado que se usará durante una conexión S2S. Cuando se configura, AppID es obligatorio y se ignoran los valores de UserID y Password.
Integrated Security Especifica que se usan las credenciales actuales de Windows para intentar crear un token para las instancias. A partir de la versión de NuGet, Microsoft.CrmSdk.XrmTooling.CoreAssembly versión 9.1.0.21

Nota

Cuando se usa el OAuth AuthType\AuthenticationType
Con fines de desarrollo y creación de prototipos, se proporcionan los siguientes identificadores appId o ClientId y URI de redirección para su uso en flujos de OAuth.
Para su uso en producción, cree un AppId o ClientId específico del inquilino en el Portal de administración de Azure.
AppId o ClientId de ejemplo = 51f81489-12ee-4a9e-aaae-a2591f45987d
RedirectUri de ejemplo = app://58145B91-0C36-4500-8554-080854F2AC97

Ejemplos de cadena de conexión

Los ejemplos siguientes muestran cómo usar cadenas de conexión para conectarse a implementaciones en línea y escenarios de autenticación. Para ver ejemplos de cadenas de conexión de instancias de implementación locales e IFD, consulte Uso de cadenas de conexión en herramientas XRM para conectarse.

Cuenta nombrada usando Office365

Cree una nueva conexión a Dataverse utilizando un nombre de usuario o contraseña a través de Office365.

Nota

Esto AuthType es obsoleto. Use OAuth como tipo de autenticación preferido. Para obtener más información, consulte Autenticación con Office365.

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

OAuth utilizando cuenta con nombre en Microsoft 365 con UX para solicitar autenticación

Crear una nueva conexión con Dataverse usando un UserID o contraseña mediante OAuth.

Nota

OAuth es el tipo de autenticación preferido para conectarse a Dataverse cuando se usa un flujo interactivo. Este tipo de autorización admite completamente las características de Microsoft Entra ID Acceso condicional y Autenticación multifactorial.

<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 utilizando el usuario de que ha iniciado la sesión actual con recurso al mensaje para autenticación

Cree una nueva conexión a Dataverse utilizando el usuario actualmente registrado a través de OAuth.

Nota

OAuth es el tipo de autenticación preferido para conectarse a Dataverse cuando se usa un flujo interactivo. Este tipo de autorización admite completamente las características de Microsoft Entra ID Acceso condicional y Autenticación multifactorial.

<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"/>

Autenticación basada en certificados

Cree una nueva conexión a Dataverse mediante una aplicación o un identificador de cliente y un certificado.

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

Autenticación basada en ClientId o secreto de cliente

Cree una nueva conexión a Dataverse mediante una aplicación o un identificador de cliente y un secreto de cliente.

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

Determinación del estado de la conexión

Para determinar si la solicitud de conexión se realizó correctamente, compruebe el valor de la propiedad CrmServiceClient.IsReady Si es true, la conexión se realiza correctamente y está listo para funcionar. De lo contrario, verifique los valores de las propiedades CrmServiceClient .LastCrmError y CrmServiceClient .LastCrmException para la causa del error de conexión.

Vea también

Crear aplicaciones cliente de Windows mediante las herramientas XRM
Usar constructores CrmServiceClient para conectarse a Dataverse
Usar herramientas XRM para ejecutar acciones en Dataverse
CrmServiceClient

  • Last updated on