Compartir a través de

Usar cadenas de conexión en útiles de XRM para conectarse a Microsoft Dataverse

  • Artículo

Con Dataverse, los útiles de XRM le permiten conectarse a su entorno de Dataverse mediante las cadenas de conexión. Esto es similar al concepto de cadenas de conexión que se utilizan con SQL Server. Las cadenas de conexión tienen compatibilidad nativa en archivos de configuración, incluida la capacidad de cifrar las secciones de configuración para máxima seguridad. Esto permite configurar las conexiones de Dataverse en tiempo de implementación, y no codificar de forma rígida en su aplicación para conectarse al entorno de Dataverse.

Crear una cadena de conexión

Especifique la cadena de conexión en el archivo app.config 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 alguna información confidencial al web.config file o app.config, como la contraseña de una cuenta, asegúrese de tomar las precauciones de seguridad adecuadas para proteger la información.

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

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

Como alternativa, puede utilizar la clase ServiceClient.

ServiceClient svc = new ServiceClient(ConnectionString);

Nota

Tendrá que usar la directiva using en siguiente el código para hacer referencia al espacio de nombres de System.Configuration para obtener acceso a la cadena de conexión en el código: using System.Configuration;

Después de crear un objeto de cliente de servicio, puede usar el objeto para realizar acciones en Dataverse. Más información: Usar útiles de XRM para ejecutar acciones en Dataverse

Parámetros de la cadena de conexión

La cadena de conexión contiene una serie de pares de name=value separados por punto y coma. La siguiente tabla muestra los parámetros admitidos, que se pueden escribir 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 OAuth, Certificate, ClientSecret y Office365 son valores permitidos para entornos Dataverse.

NOTA: El tipo de autenticación Office365 está en desuso y recomendamos usar OAuth como tipo de autenticación preferido. Más información: ¿Qué debo hacer para corregir el código de mi aplicación si se ve afectado?
RequireNewInstance Indica si se debe volver a usar una conexión existente si se vuelve a hacer la llamada mientras la conexión sigue activa. Si se establece en true, se obliga al sistema a crear una conexión única. Si se establece en false, la conexión existente se puede reutilizar.
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 Secreto de cliente para usar para 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 de los procesos establecer y configurar esta ruta.

Este parámetro es aplicable solo cuando especifica el tipo de autenticación como OAuth.
LoginPrompt Especifica si se le piden al usuario credenciales si las credenciales no se proporcionan. 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 pide al usuario que especifique credenciales. Si usa un método de conexión que no tiene interfaz de usuario, debe usar 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 está establecida, se requiere Huella digital.
Thumbprint o CertThumbprint Especifica la huella digital del certificado que se usará durante una conexión S2S. Cuando se establece, se requiere AppID y se omiten los valores UserID y Password.
Integrated Security Especifica utilizar 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
Para fines de desarrollo y creación de prototipos hemos proporcionado el siguiente AppId o ClientId y URI de redireccionamiento para uso en flujos de OAuth.
Para uso de producción, debe crear un AppId o ClientId que sea específica del inquilino en el portal de Azure Management.
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 conectar con implementaciones y escenarios de autenticación. Los ejemplos de la cadena de conexión para instancias locales y de implementación IFD están ahora disponibles en la documentación de Dynamics 365 Customer Engagement (on-premises) en: Usar cadenas de conexión en útiles de XRM para conectarse a Customer Engagement

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

Este AuthType está en desuso y recomendamos usar OAuth como el tipo de autenticación preferido. Más información: Autentique mediante 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 utilizando una aplicación o identificación 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 utilizando una aplicación o identificación 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 realizó correctamente y está listo para trabajar. De lo contrario, compruebe 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

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).