Compartir a través de

Usar cadenas de conexión en útiles de XRM

  • Artículo

Con Dynamics 365 Customer Engagement (on-premises), los útiles de XRM le permiten conectarse a la instancia mediante 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 Dynamics 365 Customer Engagement (on-premises) en tiempo de implementación, y no codificar de forma rígida en su aplicación para conectarse a la instancia.

Nota

La documentación de la cadena de conexión que es aplicable a usuarios de Dataverse ahora está disponible en la documentación de Power Apps en: Usar cadenas de conexión en útiles de XRM para conectarse a 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="MyCRMServer" connectionString="AuthType=AD;Url=https://contoso:8080/Test;" />  
</connectionStrings>

Importante

Si agrega alguna información confidencial al archivo web.config 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 pre-configured connection string named "MyCRMServer"
CrmServiceClient crmSvc = new CrmServiceClient(ConfigurationManager.ConnectionStrings["MyCRMServer"].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 CrmServiceClient, puede usar el objeto para realizar acciones en Dynamics 365 Customer Engagement (on-premises). Más información: Usar útiles de XRM para ejecutar acciones

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 del parámetro Descripción
ServiceUri, Service Uri, Url o Server Especifica la dirección URL a Dynamics 365 Server. 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 de https://crm-server:port/organization-name o para Dynamics 365 Customer Engagement (on-premises).

Se requiere el nombre de la organización. Puede especificar el nombre descriptivo o único de la organización a la que conectarse.

Ejemplo: https://contoso/test, https://contoso:5555/test, https://contoso/test, o https://10.10.10.2/test.
Domain Especifica el dominio que comprobará las credenciales de usuario.
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 a Dynamics 365 Customer Engagement (on-premises). Los valores válidos son: AD, IFD (AD FS habilitado), OAuth o Office365.

- AD y IFD solo se permiten para instancias de Dynamics 365 Customer Engagement (on-premises).
- OAuth se permite para las instancias de Dynamics 365 Customer Engagement (on-premises) y Dataverse. Para el registro local, ADFS 3.x+ y App\Id. de cliente con ADFS se requieren para el tipo OAuth.
- Office365 se permite para instancias de Dataverse solo.
- El uso de un certificado o secreto de cliente para la autenticación se admite en Dataverse pero no en Dynamics 365 Customer Engagement (on-premises).
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. El valor predeterminado es false que indica que la conexión existente se reutilizará. Si se establece en true, se obliga al sistema a crear una conexión única.
ClientId, AppId o ApplicationId Especifica el ClientID asignado cuando se registró su aplicación en Azure Active Directory o Servicios de federación de Active Directory (AD FS).
RedirectUri o ReplyUrl Especifica el URI de redirección de la aplicación que registró en Azure Active Directory 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.
SkipDiscovery Especifica si se llama detección de instancia para determinar el uri de conexión para una instancia determinada. A partir de la versión de NuGet Microsoft.CrmSdk.XrmTooling.CoreAssembly Versión 9.0.2.7, predeterminado = true. Las versiones más antiguas establecen de forma predeterminada false.
Nota: Si se establece en true, es importante que el usuario proporcione el URI correcto y preciso para la instancia de destino.
Thumbprint o CertificateThumbprint 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.
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.

Nota

Al usar el tipo de autenticación de OAuth 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. Los usamos en todos nuestros ejemplos de código.

AppId o ClientId de ejemplo = 51f81489-12ee-4a9e-aaae-a2591f45987d
RedirectUri de ejemplo = app://58145B91-0C36-4500-8554-080854F2AC97

Para uso de producción, debe crear un AppId o ClientId que sea específica del inquilino en el portal de Azure Management.

Ejemplos de cadena de conexión

Los ejemplos siguientes muestran cómo usar cadenas de conexión para conectar con implementaciones de Dynamics 365 Customer Engagement (on-premises) e IFD. Los ejemplos de la cadena de conexión para las instancias de Dataverse están ahora disponibles en la documentación de Power Apps en: Usar cadenas de conexión en útiles de XRM para conectarse a Dataverse

Autenticación local integrada

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

Cuenta con nombre utilizando autenticación local

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

OAuth utilizando cuenta con nombre en Dynamics 365 Customer Engagement (on-premises) con UX para solicitar autenticación

Crear una nueva conexión mediante un UserID o contraseña mediante oAuth.

Nota

OAuth es el tipo autenticación preferido para conectarse a Dynamics 365 Customer Engagement (on-premises) al usar un flujo interactivo. Este tipo de autorización admite completamente las características de Azure Active Directory Acceso condicional y Autenticación multifactorial.

<add name="MyCRMServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith;
  Password=passcode;
  Url=https://contoso:8080/Test;
  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

Crear una nueva conexión con el usuario que ha iniciado la sesión actual mediante oAuth.

Nota

OAuth es el tipo autenticación preferido para conectarse a Dynamics 365 Customer Engagement (on-premises) al usar un flujo interactivo. Este tipo de autorización admite completamente las características de Azure Active Directory Acceso condicional y Autenticación multifactorial. Para aprender más sobre el parámetro Integrated Security, vea el tema aquí .

<add name="MyCRMServer"
 connectionString="
  AuthType=OAuth;
  Username=jsmith;
  Integrated Security=true;
  Url=https://contoso:8080/Test;
  AppId=51f81489-12ee-4a9e-aaae-a2591f45987d;
  RedirectUri=app://58145B91-0C36-4500-8554-080854F2AC97;
  TokenCacheStorePath=c:\MyTokenCache;
  LoginPrompt=Auto"/>

IFD utilizando una cuenta con nombre con delegación a un subdominio

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

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, 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 Dynamics 365 Customer Engagement (on-premises) y Dataverse
Usar útiles de XRM para ejecutar acciones
CrmServiceClient