Uso de la herramienta Endpoint Model Generator para clientes de API REST

Introducción

Al integrar Acumatica utilizando la API REST, es muy útil usar Acumatica.RESTClient.dll.   El equipo de desarrollo de Acumatica ha proporcionado esta herramienta en Github en la siguiente URL:  Acumatica/AcumaticaRESTAPIClientForCSharp (github.com)

Parte de este repositorio es el código completo de una herramienta que crea todos los modelos para un endpoint determinado, que se puede utilizar junto con el RESTClient. Esta herramienta se llama EndpointModelGenerator.

Descargue la última versión de este repositorio completo, ya que los cambios de código se realizarán tanto en Acumatica.REST.API.Client.sln como en EndpointModelGenerator.sln.

En mi entrada de blog anterior, Integración usando el cliente de la API REST con el módulo de fabricación de Acumatica, describo cómo usar los modelos existentes para los endpoints DEFAULT y MANUFACTURING. Pero ¿qué pasa si necesita personalizar estos endpoints o crear uno nuevo?

El código de EndpointModelGenerator proporcionado en Github es una aplicación de escritorio en C# que utiliza la salida JSON de la definición de Open API de un endpoint de servicios web y crea las clases C# asociadas que se pueden usar con RESTClient.dll. Veamos los pasos sobre cómo funciona esto.

Debe abrir la solución en Visual Studio 2022, ya que requiere .Net 6. Compile y ejecute el proyecto tal cual, y se le pedirá que realice 3 pasos:

• Introduzca la ruta a un proyecto de Visual Studio que contendrá los modelos.
• Pegue el JSON para el endpoint
• Haga clic en un botón para generar los archivos C# para los modelos.

Esto es bastante sencillo, pero hay un trabajo de preparación que hacer.

Requisitos previos

Para empezar, he extendido el endpoint DEFAULT a uno nuevo llamado DEVMVPBlog, versión 20.200.001. Vea a continuación la captura de pantalla de este endpoint. Hay una nueva entidad en este endpoint para problemas de inventario, que falta en el endpoint DEFAULT. Cualquiera de sus endpoints personalizados a partir de la versión 20 o superior funcionará de la misma manera.

A continuación, cree un nuevo proyecto dentro de la solución Acumatica.REST.Client. Para este ejemplo, el proyecto se añade a la carpeta Endpoints. Es una biblioteca de clases C#, y la he llamado Acumatica.DEVMVPBlog_20.200.001 para mantener la misma convención de nomenclatura que utilizan los proyectos de endpoint existentes. El proyecto se crea con un único archivo de clase vacío, como se muestra:

Elimine el archivo Class1.cs ya que no se utilizará, y luego guarde los cambios en la solución.

A continuación, debe volver al endpoint personalizado, hacer clic en los puntos suspensivos (…) y elegir OpenAPI 2.0. Se mostrará una nueva pestaña con la representación JSON de la definición del endpoint. (ver ejemplos a continuación)

Los datos JSON de mi endpoint extendido son MUY largos, más de 95000 líneas. Es demasiado grande para pegarlo en el cuadro de texto del EndpointModelGenerator, así que opté por modificar la forma en que funciona el EndpointModelGenerator en el código base. Así que, para este paso, guardé el texto JSON de la página web en un archivo de texto con la extensión .json.

Luego modifiqué el código del EndpointModelGenerator para pedir al usuario que buscara el archivo de esquema del endpoint .json en lugar de pegarlo directamente en el campo de texto. Luego, cambié el botón Generar para que abriera el archivo y lo usara en el propio proceso de generación.

El formulario ahora se ve así, con los Pasos (1), (2) y (3) definidos como botones.

Los cambios de código en el proceso de generación se muestran aquí:

 GIST: https://gist.github.com/dianecawley/2018d5f1cc4146966848056bd6b45f6f

Ejecutar el generador de modelos

Ahora que todo está preparado, es hora de ejecutar el Generador y ver los resultados.

Paso (1) – Haga clic en Seleccionar proyecto. Busque el archivo .csproj que se creó para usar con la nueva definición de endpoint y haga clic en Abrir.

Observe que varios otros cuadros de texto se rellenan con la información necesaria para continuar con la generación de los modelos.

Paso (2) – Haga clic en Seleccionar archivo de esquema JSON. Busque el archivo .json que se creó a partir de la definición de Open API de Acumatica y haga clic en Abrir.

La ruta del archivo se muestra en el formulario.

Paso (3) – Haga clic en el botón Generar.  Aquí es donde se realiza todo el trabajo.  El cuadro de texto del registro se rellenará con cada una de las entidades del punto final a medida que se procesan.

Verifique los resultados en el código del cliente REST API

Abra la solución Acumatica.REST.API.Client.  Observe que el proyecto Acumatica.DEVMVPBlog_20.200.001 ahora se ha rellenado con las subcarpetas API y Model, y todas las entidades del punto final ahora tienen definiciones de clase adecuadas.  He abierto la clase InventoryIssue ya que fue la razón principal del nuevo punto final en este ejemplo.

La compilación de la solución creará el archivo Acumatica.DEVMVPBlog_20.200.001.dll, que luego podrá utilizarse en su proyecto de código de integración.

Utilice el .dll resultante del punto final

Abra su solución de integración y añada una referencia al .dll del punto final recién creado (a partir de la compilación de la sección anterior).

Luego, añada las declaraciones 'using' para las clases *.Api y *.Model dentro del .dll referenciado.  Consulte el ejemplo a continuación.

A continuación se muestra un fragmento de código que utiliza el objeto InventoryIssues recién disponible

GIST: https://gist.github.com/dianecawley/842df182253669de0a2d37c429ec1b76

Conclusión

El Generador de Modelos de Punto Final es un verdadero ahorro de tiempo cuando se ha creado un punto final personalizado en Acumatica y un software de terceros necesita utilizar el cliente REST API para la integración.  Aunque se necesitan algunos pasos en el proceso de creación de los modelos de punto final, son muchos menos que escribir las clases individualmente.  Muchas gracias a Dmitrii Naumov por crear el Cliente REST API, así como el Generador de Modelos.  Como ISV de Acumatica con un producto conectado, nuestro equipo ahorra tiempo al utilizar estas herramientas.

¡Feliz codificación!