Ejemplo simple de inicio rápido de la API Web (C#)

Artículo
04/18/2017

Se aplica a: Dynamics 365 (online), Dynamics 365 (on-premises)

Este ejemplo se muestra cómo autenticarse con un Microsoft Dynamics 365 Server y luego llamar a una operación de la API web básica, la WhoAmI Function. A diferencia de otros ejemplos de la API web, este ejemplo no depende de otras bibliotecas de código auxiliar no estándar o de archivos de origen adicionales. Todo su código fuente está en un archivo, Program.cs para ayudarle a que el flujo de lógica y el proceso de autenticación sean más fáciles de comprender. El ejemplo funcionará con implementaciones en línea, locales y con conexión a Internet (IFD).

Requisitos

Este ejemplo tiene los requisitos siguientes:

Para abrir y crear la solución, Microsoft Visual Studio 2015 o posterior es necesario. Las versiones gratuitas de este producto se encuentran disponibles para descarga: Visual Studio Express o Comunidad de Visual Studio.
Una conexión con Internet o de red para conectarse a su Microsoft Dynamics 365 Server en línea o local, respectivamente.
Una cuenta de usuario en su Microsoft Dynamics 365 Server (en línea o local).
Si se usa Dynamics 365 (online), la aplicación de ejemplo debe ser Azure Active Directory registrada, tal como se describe en Tutorial: Registrar una aplicación de Dynamics 365 con Azure Active Directory .
Si se usa Dynamics 365 (local) con Implementación con conexión a Internet (IFD), la aplicación de ejemplo debe registrarse con el inquilino de Active Directory, tal como se describe en Tutorial: Registrar una aplicación de Dynamics 365 con Active Directory.

Importante

Por diseño, inicialmente la solución no se creará correctamente. El código de origen se debe editar en las líneas indicadas por comentarios //TODO para suministrar información de cuenta de usuario y/o registro de la aplicación.

Demostraciones

Este sencillo ejemplo demuestra dos conceptos básicos necesarios para desarrollo mediante la API web: autenticación con un Microsoft Dynamics 365 Server y formar llamadas de la API web básicas mediante el protocolo HTTP.

Se requiere autenticación antes de que una aplicación cliente pueda obtener acceso a un recurso de Dynamics 365. Este proceso puede resultar no trivial por dos razones: se requieren mecanismos de autenticación diferentes para los diferentes tipos de implementación, y los mecanismos de autenticación basados en la web suelen incluir varios pasos de programación. La autenticación integrada de Windows, requerida para implementaciones locales, es relativamente sencilla, y requiere solo un nombre de usuario y una contraseña. A continuación, el programa actúa como agente del usuario autenticado.

En cambio, las implementaciones en línea y IFD requieren el registro previo de la aplicación cliente, y después usa un proceso de autenticación OAuth de varios pasos. El proceso de registro para Dynamics 365 (online) se describe en el artículo Tutorial: Registrar una aplicación de Dynamics 365 con Azure Active Directory. El proceso de registro para Dynamics 365 (local) con Implementación con conexión a Internet (IFD) se describe en el artículo Tutorial: Registrar una aplicación de Dynamics 365 con Active Directory. Cada solicitud de la API web posterior debe autenticarse con OAuth. Afortunadamente, gran parte de la complejidad de la autenticación OAuth se puede simplificar mediante el uso de las bibliotecas de autenticación de Active Directory (ADAL) para clientes .NET, que se agrega al ejemplo como el paquete NuGet Microsoft.IdentityModel.Clients.ActiveDirectory. La autorización OAuth se encapsula aún más en este ejemplo con la inclusión de la clase OAuthMessageHandler, que agrega el encabezado de autorización OAuth requerido a las solicitudes del mensaje. En ejemplos futuros, la compatibilidad de la funcionalidad de autenticación se separa en la Biblioteca de código auxiliar de la API web. Para obtener más información, vea Autenticar usuarios en Microsoft Dynamics 365.

La API web de Dynamics 365 es una API REST basada en la Especificación de OData, por lo que admite solicitudes HTTP estandarizadas con entidades y las llamadas a funciones y acciones. Este ejemplo demuestra la llamada a la función WhoAmI Function con una solicitud GET, después el uso de la información proporcionada por esta función en la respuesta HTTP resultante. Este ejemplo aprovecha varias bibliotecas estándar para ayudar en esta invocación:

Las clases .NET Framework de los nombres de espacio System.Net y System.Net.Http se usan para la comunicación HTTP.
Dado que C# carece de compatibilidad nativa para JSON, el Json.NET Framework de código abierto se incluye con su paquete NuGet.
La programación asincrónica es compatible con el espacio de nombres System.Threading.Tasks. Debido a retrasos potenciales, el acceso web emplea normalmente mecanismos asincrónicos. Para obtener más información, consulte Programación asincrónica con Async y Await.

Ejecute este ejemplo

Primero vaya a Ejemplo simple de inicio rápido de la API web (C#), descargue el archivo de ejemplo, Simple Web API quick-start sample (CS.zip), y extraiga su contenido en una carpeta local. Esta carpeta debe contener los siguientes archivos:

Archivo	Objetivo/descripción
Program.cs	Contiene el código de origen para este ejemplo.
SimpleWebApi.sln SimpleWebApi.csproj packages.config AssemblyInfo.cs App.config	La solución de Microsoft Visual Studio 2015 estándar, proyecto, configuración del paquete NuGet, y archivos de información de ensamblado y archivos de configuración de la aplicación para este ejemplo.

A continuación, use el procedimiento siguiente para ejecutar este servicio.

Busque y haga doble clic en el archivo de la solución, SimpleWebApi.sln, para cargar la solución en Visual Studio.
En el Explorador de soluciones, haga doble clic en el archivo Program.cs para abrirlo en el editor.
Busque los comentarios //TODO en el método Main, agregue los valores de cadena de conexión requeridos y quite las marcas de comentario de las líneas asociadas.
Cree la solución SimpleWebApi. Debe descargar e instalar automáticamente todos los paquetes NuGet necesarios que faltan o deben actualizarse.
Ejecute el proyecto SimpleWebApi desde Visual Studio. Todas las soluciones de ejemplo se configuran para ejecutarse en modo de depuración de forma predeterminada.
El comportamiento depende del tipo de implementación.
- Para implementaciones en línea e IFD, la aplicación de consola abrirá una nueva ventana para especificar sus credenciales y contraseña de usuario.
- En implementaciones locales, la aplicación de consola le solicitará una contraseña para la cuenta de Dynamics 365 suministrada.
Suministre esta información y presione Enter.

Lista de código

El origen más actual de este archivo se encuentra en el paquete de descarga de ejemplo.

Program.cs

namespace Microsoft.Crm.Sdk.Samples
{
    /// <summary>
    /// A basic Web API client application for Dynamics 365 (CRM). This sample authenticates 
    /// the user and then calls the WhoAmI Web API function. 
    /// </summary>
    /// <remarks> 
    /// Prerequisites: 
    ///   -  To run this application, you must have a CRM Online or on-premise account. 
    ///   -  For CRM Online or Internet-facing deployments (IFD), the application must be registered  
    ///      with Azure Active Directory as described in this article: 
    ///      https://msdn.microsoft.com/en-us/library/dn531010.aspx
    ///   
    /// The WhoAmI Web API function is documented here: 
    ///    https://msdn.microsoft.com/en-us/library/mt607925.aspx
    /// </remarks>
    static class SimpleWebApi
    {
        //TODO: Uncomment then substitute your correct Dynamics 365 organization service 
        // address for either CRM Online or on-premise (end with a forward-slash).
        //private static string serviceUrl = "https://mydomain.crm.dynamics.com/myorg/";   // CRM Online
        //private static string serviceUrl = "https://<organization name>.<domain name>/";   // CRM IFD
        //private statics string serviceUrl = "http://myserver/myorg/";        // CRM on-premises

        //TODO: For an on-premises deployment, set your organization credentials here. (If
        // online or IFD, you can you can disregard or set to null.)
        private static string userAccount = "<user-account>";  //CRM user account
        private static string domain = "<server-domain>";  //CRM server domain

        //TODO: For CRM Online or IFD deployments, substitute your app registration values  
        // here. (If on-premise, you can disregard or set to null.)
        private static string clientId = "<app-reg-guid>";     //e.g. "e5cf0024-a66a-4f16-85ce-99ba97a24bb2"
        private static string redirectUrl = "<redirect-URL>";  //e.g. "https://localhost/SdkSample"

        static public void Main(string[] args)
        {
            //One message handler for OAuth authentication, and the other for Windows integrated 
            // authentication.  (Assumes that HTTPS protocol only used for CRM Online.)
            HttpMessageHandler messageHandler;
            if (serviceUrl.StartsWith("https://"))
            {
                messageHandler = new OAuthMessageHandler(serviceUrl, clientId, redirectUrl,
                         new HttpClientHandler());
            }
            else
            {
                //Prompt for user account password required for on-premise credentials.  (Better
                // approach is to use the SecureString class here.)
                Console.Write("Please enter the password for account {0}: ", userAccount);
                string password = Console.ReadLine().Trim();
                NetworkCredential credentials = new NetworkCredential(userAccount, password, domain);
                messageHandler = new HttpClientHandler() { Credentials = credentials };
            }
            try
            {
                //Create an HTTP client to send a request message to the CRM Web service.
                using (HttpClient httpClient = new HttpClient(messageHandler))
                {
                    //Specify the Web API address of the service and the period of time each request 
                    // has to execute.
                    httpClient.BaseAddress = new Uri(serviceUrl);
                    httpClient.Timeout = new TimeSpan(0, 2, 0);  //2 minutes

                    //Send the WhoAmI request to the Web API using a GET request. 
                    var response = httpClient.GetAsync("api/data/v8.1/WhoAmI",
                            HttpCompletionOption.ResponseHeadersRead).Result;
                    if (response.IsSuccessStatusCode)
                    {
                        //Get the response content and parse it.
                        JObject body = JObject.Parse(response.Content.ReadAsStringAsync().Result);
                        Guid userId = (Guid)body["UserId"];
                        Console.WriteLine("Your system user ID is: {0}", userId);
                    }
                    else
                    {
                        Console.WriteLine("The request failed with a status of '{0}'",
                               response.ReasonPhrase);
                    }
                }
            }
            catch (Exception ex)
            {
                DisplayException(ex);
                throw;
            }
            finally
            {
                Console.WriteLine("Press <Enter> to exit the program.");
                Console.ReadLine();
            }
        }

        /// <summary> Displays exception information to the console. </summary>
        /// <param name="ex">The exception to output</param>
        private static void DisplayException(Exception ex)
        {
            Console.WriteLine("The application terminated with an error.");
            Console.WriteLine(ex.Message);
            while (ex.InnerException != null)
            {
                Console.WriteLine("\t* {0}", ex.InnerException.Message);
                ex = ex.InnerException;
            }
        }
    }

    /// <summary>
    ///Custom HTTP message handler that uses OAuth authentication thru ADAL.
    /// </summary>
    class OAuthMessageHandler : DelegatingHandler
    {
        private AuthenticationHeaderValue authHeader;

        public OAuthMessageHandler(string serviceUrl, string clientId, string redirectUrl,
                HttpMessageHandler innerHandler)
            : base(innerHandler)
        {
            // Obtain the Azure Active Directory Authentication Library (ADAL) authentication context.
            AuthenticationParameters ap = AuthenticationParameters.CreateFromResourceUrlAsync(
                    new Uri(serviceUrl + "api/data/")).Result;
            AuthenticationContext authContext = new AuthenticationContext(ap.Authority, false);
            //Note that an Azure AD access token has finite lifetime, default expiration is 60 minutes.
            AuthenticationResult authResult = authContext.AcquireToken(serviceUrl, clientId, new Uri(redirectUrl));
            authHeader = new AuthenticationHeaderValue("Bearer", authResult.AccessToken);
        }

        protected override Task<HttpResponseMessage> SendAsync(
                 HttpRequestMessage request, System.Threading.CancellationToken cancellationToken)
        {
            request.Headers.Authorization = authHeader;
            return base.SendAsync(request, cancellationToken);
        }
    }
}

Ver también

Web API Reference
Ejemplos de la API web
Use la biblioteca de código auxiliar de la API web de Microsoft Dynamics 365 (C#)
Autenticar usuarios en Microsoft Dynamics 365

Microsoft Dynamics 365

Compartir a través de