Ejemplos de la API web (C#)

Publicado: enero de 2017

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

En este tema se proporciona información sobre los ejemplos de la API web implementada con C#. Si bien cada ejemplo se centra en un aspecto distinto de la API web de Microsoft Dynamics 365, comparten características y estructura similares.

En este tema

Requisitos previos

Lista de ejemplos de la API web (C#)

Cómo descargar y ejecutar los ejemplos

Elementos comunes que se encuentran en cada ejemplo

Requisitos previos

Los siguientes elementos son necesarios para crear y ejecutar los ejemplos en C# de la API web de Dynamics 365:

• Una versión Microsoft Visual Studio de 2015 o posterior. Una versión gratuita, Visual Studio Community, está disponible para descarga aquí.

• Una conexión con Internet para descargar y actualizar los paquetes NuGet a los que se hace referencia.

• Acceso a Dynamics Dynamics 365 Online o local (o posterior). Para todos los tipos de instalación de Dynamics 365, se necesita una cuenta de usuario con privilegios para realizar operaciones CRUD.

• Para ejecutar ejemplos con Dynamics 365 (online), debe registrar la aplicación con Azure Active Directory para obtener un Id. de cliente y una dirección URL de redirección. Para obtener más información, vea Tutorial: Registrar una aplicación de Dynamics 365 con Azure Active Directory.

Lista de ejemplos de la API web (C#)

En la siguiente tabla se muestran los ejemplos implementados en C#. Cada ejemplo se describe en forma más general en un tema de grupo de ejemplo correspondiente que se centra en la solicitud HTTP y mensajes de respuesta, como se detalla en el tema Ejemplos de la API web.

Cómo descargar y ejecutar los ejemplos

El código de origen para cada ejemplo está disponible en Galería de código de MSDN. El vínculo para descargar cada ejemplo se incluye en el tema de ejemplo. La descarga de ejemplos es un archivo .zip comprimido que contiene archivos de la solución Visual Studio 2015 para el ejemplo. Para obtener más información, consulte la sección Ejecutar este ejemplo en cada tema de ejemplo.

Elementos comunes que se encuentran en cada ejemplo

La mayoría de los ejemplos tienen una estructura similar y contienen métodos y recursos comunes, normalmente para proporcionar la infraestructura básica para un programa en C# de la API web.

Muchos de estos elementos comunes también están presentes al crear una nueva solución que tendrá acceso a la API web de Dynamics 365. Para obtener más información, vea Iniciar un proyecto de la web API de Dynamics 365 en Visual Studio (C#).

Bibliotecas y marcos de trabajo usados

Esta implementación en C# depende del siguiente código auxiliar para la comunicación HTTP, la configuración de aplicaciones, la autenticación, el tratamiento de errores, y la serialización de JSON.

• Las clases de mensajería estándar HTTP de .NET Framework que se contienen en el espacio de nombres System.Net.Http, en particular HttpClient, HttpRequestMessage, y HttpResponseMessage, se usan para mensajería HTTP.

• La biblioteca de código auxiliar de la API web de Dynamics 365 se usa para leer el archivo de configuración de la aplicación, para autenticarse en el servidor de Dynamics 365, y ayudar en el tratamiento de errores de operaciones. Para obtener más información, vea Use la biblioteca de código auxiliar de la API web de Microsoft Dynamics 365 (C#).

• La biblioteca Json.NET de Newtonsoft admite el formato de datos JSON.

Biblioteca de Json.NET

Dado que C# y la mayoría de los otros lenguajes administrados no admiten nativamente el formato de datos de JSON, la mejor opción actual es usar una biblioteca para esta funcionalidad. Para obtener más información, consulte Introducción a la notación de objetos de JavaScript (JSON) en JavaScript y .NET. Json.NET es una opción popular para proyectos de Microsoft .NET. Proporciona un marco de trabajo sólido, de alto rendimiento y código abierto (con licencia MIT) para serializar, convertir, analizar, consultar y dar formato a datos JSON. Para obtener más información, vea la documentación de Json.NET.

En los ejemplos de C#, esta biblioteca se usa principalmente para serializar datos entre objetos .NET y los cuerpos de mensajes HTTP. Aunque la biblioteca proporciona varios métodos para realizar esta tarea, el enfoque usado por los ejemplos es crear instancias JObject individuales para representar instancias de entidad de Dynamics 365 (registros). Por ejemplo, el siguiente código crea la variable contact1 que representa una instancia contact EntityType de Dynamics 365, después suministra valores para un conjunto seleccionado de propiedades para este tipo.

JObject contact1 = new JObject();
contact1.Add("firstname", "Peter");
contact1.Add("lastname", "Cambel");
contact1.Add("annualincome", 80000);
contact1["jobtitle"] = "Junior Developer";

El uso de la notación entre llaves en la última instrucción es equivalente al método Add. Esta creación de instancias también podría conseguirse mediante el uso del método estático Parse:

JObject contact1 = JObject.Parse(@"{firstname: 'Peter', lastname: 'Cambel', "
+ @"annualincome: 80000, jobtitle: 'Junior Developer'}");

Puesto que JObject representa un tipo JSON general, su uso evita mucha comprobación de tipos en tiempo de ejecución. Por ejemplo, aunque la declaración siguiente es sintácticamente válida, potencialmente producirá los errores en tiempo de ejecución porque el contact EntityType no contiene una propiedad age.

contact1.Add("age", 37); //Possible error--no age property exists in contact!

Una vez que se ha inicializado la variable de entidad, puede enviarse en el cuerpo de un mensaje, con ayuda de varias clases System.Net.Http, por ejemplo:

HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "contacts");
request.Content = new StringContent(contact1.ToString(), Encoding.UTF8, "application/json");
HttpResponseMessage response = await httpClient.SendAsync(request1);

También puede crear instancias JObject deserializando instancias de entidad durante operaciones de recuperación, por ejemplo:

//contact2Uri contains a reference to an existing CRM contact instance.
string queryOptions = "?$select=fullname,annualincome,jobtitle,description";
HttpResponseMessage response = await httpClient.GetAsync(contact2Uri + queryOptions);
JObject contact2 = JsonConvert.DeserializeObject<JObject>(await response.Content.ReadAsStringAsync());

Tratamiento de errores y aciertos de respuesta

En general, los ejemplos adoptan un enfoque directo procesar respuestas HTTP. Si la solicitud se realiza correctamente, la información sobre la operación se envía normalmente a la consola. Si la respuesta también contiene una carga útil de JSON o encabezados útiles, esta información se procesa si se ha realizado correctamente. Y, por último, si se creó una entidad de Dynamics 365, la colección entityUris se actualizará con el URI de ese recurso. El método Método DeleteRequiredRecords usa esta colección para eliminar opcionalmente los datos creados por el ejemplo desde el servidor de Dynamics 365.

Si se produce error en la solicitud, el programa envía un mensaje contextual sobre la operación que ha producido error y, a continuación inicia una excepción personalizada de tipo CrmHttpResponseException. El controlador de excepciones genera más información sobre la excepción y después controla los pases a un bloque finally que incluye lógica de limpieza, una vez más incluyendo una llamada a DeleteRequiredRecords. El siguiente código demuestra este método de tratamiento de errores en una solicitud POST para crear un registro.

if (response.StatusCode == HttpStatusCode.NoContent)  //204
{
Console.WriteLine("POST succeeded, entity created!”);
//optionally process response message headers or body here, for example:
entityUri = response.Headers.GetValues("OData-EntityId").FirstOrDefault();
entityUris.Add(entityUri);
}
else
{
Console.WriteLine("Operation failed: {0}", response.ReasonPhrase);
throw new CrmHttpResponseException(response.Content);
}

HttpStatusCode.NoContent es equivalente a un código de estado HTTP 204, “Sin contenido”. Aquí, este código de estado indica que la solicitud POST se realizó correctamente. Para obtener más información, consulte Componer solicitudes HTTP y administrar errores.

Características y métodos

La mayoría de los ejemplos tienen el mismo patrón arquitectónico general, con las siguientes características:

• Todo el código de ejemplo correspondiente en C# se contiene en el archivo de origen primario denominado Program.cs, que contiene una sola clase con el mismo nombre que el proyecto de ejemplo.

• Las clases de ejemplo, así como la Use la biblioteca de código auxiliar de la API web de Microsoft Dynamics 365 (C#), se contienen en el espacio de nombres Microsoft.Crm.Sdk.Samples.

• Los ejemplos se comentan generosamente: se proporcionan resúmenes en los niveles de clase y método, y la mayoría de las instrucciones individuales clave tienen comentarios asociados en la misma línea o en una sola. Los archivos complementarios, como el archivo de configuración de la aplicación App.config, también contienen a menudo comentarios importantes.

• La clase de ejemplo principal está estructurada normalmente para contener el siguiente conjunto común de métodos: Método principal, Método ConnectToCRM, Método CreateRequiredRecords, Método RunAsync, Método DisplayException, y Método DeleteRequiredRecords.

Método principal

Por definición, este método comienza la ejecución del ejemplo. Contiene sólo el flujo de control de alto nivel y la lógica de control de excepciones, a menudo exactamente como el siguiente código:

static void Main(string[] args)
{
FunctionsAndActions app = new FunctionsAndActions();
try
{
//Read configuration file and connect to specified CRM server.
app.ConnectToCRM(args);
app.CreateRequiredRecords();
Task.WaitAll(Task.Run(async () => await app.RunAsync()));
}
catch (System.Exception ex) { DisplayException(ex);
}
finally
{
if (app.httpClient != null)
{
app.DeleteRequiredRecords(true);
app.httpClient.Dispose();
}
Console.WriteLine("Press <Enter> to exit the program.");
Console.ReadLine();
}
}

Método ConnectToCRM

Este método llama a las bibliotecas de código auxiliar para leer el archivo de configuración de la aplicación y después establece una conexión con el servidor de Dynamics 365 especificado. El resultado de estos pasos es la inicialización de una propiedad de clase HttpClient que se usa en todo el programa para enviar solicitudes web y recibir respuestas. Tenga en cuenta que las propiedades siguientes se establecen en este objeto:

//Define the Web API address, the max period of execute time, the Odata
// version, and the expected response payload format.
httpClient.BaseAddress = new Uri(config.ServiceUrl + "api/data/v8.1/");
httpClient.Timeout = new TimeSpan(0, 2, 0);  // 2 minute timeout
httpClient.DefaultRequestHeaders.Add("OData-MaxVersion", "4.0");
httpClient.DefaultRequestHeaders.Add("OData-Version", "4.0");
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

Para obtener más información sobre la configuración y autenticación de aplicaciones de ejemplo, vea Use la biblioteca de código auxiliar de la API web de Microsoft Dynamics 365 (C#).

Método CreateRequiredRecords

Este método crea e inicializa los registros de entidad requeridos por el ejemplo, solo cuando estas operaciones no son de interés principal en el ejemplo. Por ejemplo, el Ejemplo de operaciones básicas de la API web (C#) no contiene este método porque la creación de registros es un aspecto principal del ejemplo.

Método RunAsync

Este método asincrónico contiene el código de origen correspondiente o, para programas más largos, métodos de llamada que agrupan el código de ejemplo correspondiente. El código contenido se explica por comentarios incrustados y comentario situado en la sección Comentarios de cada tema de ejemplo correspondiente.

Método DisplayException

Este método auxiliar muestra información de excepciones, incluidas las excepciones internas, a la consola estándar.

Método DeleteRequiredRecords

Este método complementario elimina opcionalmente registros de ejemplo y otros recursos del servidor de Dynamics 365 creados en el programa y, en particular, por el método Método CreateRequiredRecords. Consulta al usuario para la comprobación de esta operación, después itera a través de la colección entityUris e intenta eliminar cada elemento con un mensaje HTTP DELETE.

Ver también

Use la API web de Microsoft Dynamics 365
Ejemplos de la API web
Ejemplos de la API web (JavaScript del lado del cliente)
Ejemplo de operaciones básicas de la API web (C#)
Ejemplo de datos de consulta API (C#)
Ejemplo de operaciones condicionales de la API web (C#)
Ejemplo de funciones y acciones de la API web (C#)

Microsoft Dynamics 365

© 2017 Microsoft. Todos los derechos reservados. Copyright