Uso de cadenas de conexión en herramientas XRM

Con Dynamics 365 Customer Engagement (on-premises), las herramientas XRM le permiten conectarse a su 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 le permite configurar las conexiones de Dynamics 365 Customer Engagement (on-premises) en el momento de la implementación, y no el código de la aplicación para conectarse a la instancia.

Nota:

La documentación de cadenas de conexión que se aplica a los usuarios de Dataverse ahora está disponible en la documentación de Power Apps en: Usar cadenas de conexión en herramientas 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 información confidencial al app.config archivo o web.config , por ejemplo, una contraseña de 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 siguiente using directiva en su código para referirse al espacio de nombres System.Configuration para acceder a la cadena de conexión en su código: using System.Configuration;

Después de crear un CrmServiceClient objeto, puede usarlo para realizar acciones en Dynamics 365 Customer Engagement (on-premises). Más información: Usar herramientas 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, Urlo Server	Especifica la dirección URL del servidor de Dynamics 365. 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 tener el formato de https://crm-server:port/organization-name 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 verificará las credenciales de usuario.
UserName, User Name, UserIdo 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), OAutho Office365. - AD y IFD solo se permiten para instancias de Dynamics 365 Customer Engagement (on-premises). - OAuthestá permitido 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 solo se permite para instancias de Dataverse. - 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 el que indica que se va a reutilizar la conexión existente. 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 redireccionamiento de la aplicación registrada 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: solicita 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 debe llamar a la detección de instancias para determinar el URI de conexión de una instancia determinada. A partir de la versión NuGet Microsoft.CrmSdk.XrmTooling.CoreAssembly Version 9.0.2.7, predeterminado = true. Las versiones anteriores tienen como falsevalor predeterminado . 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 OAuth autenticación con fines de desarrollo y creación de prototipos, hemos proporcionado el siguiente AppId o ClientId y URI de redireccionamiento para su uso en flujos de OAuth. Los usamos en todos nuestros ejemplos de código.

Ejemplo AppId o ClientId = 00001111-aaaa-2222-bbbb-3333cccc4444
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

En los ejemplos siguientes se muestra cómo puede usar cadenas de conexión para conectarse a implementaciones de Dynamics 365 Customer Engagement (on-premises) e IFD. Los ejemplos de cadenas de conexión para instancias de Dataverse ahora están disponibles en la documentación de Power Apps en: Usar cadenas de conexión en herramientas 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 la autenticación

Cree una nueva conexión con un ID de usuario o una contraseña a través de oAuth.

Nota:

OAuth es el tipo de autenticación preferido para conectarse a Dynamics 365 Customer Engagement (on-premises) cuando se usa un flujo interactivo. Este tipo de autenticación es totalmente compatible con las características del acceso condicional de Azure Active Directory y la autenticación multifactor.

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

Cree una nueva conexión utilizando el usuario que ha iniciado sesión actualmente a través de oAuth.

Nota:

OAuth es el tipo de autenticación preferido para conectarse a Dynamics 365 Customer Engagement (on-premises) cuando se usa un flujo interactivo. Este tipo de autenticación es totalmente compatible con las características del acceso condicional de Azure Active Directory y la autenticación multifactor. Para obtener más información sobre el Integrated Security parámetro, consulte el tema aquí.

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

Consulte también

Compilar aplicaciones cliente de Windows mediante las herramientas XRM
Utiliza los constructores de CrmServiceClient para conectarte a Dynamics 365 Customer Engagement (local) y Dataverse
Utilice las herramientas XRM para ejecutar acciones
CrmServiceClient