Escribir flujos de trabajo codificados compatibles con lienzos

Recomendaciones para estructurar flujos de trabajo codificados para que el Visor de código bajo los represente como diagramas de código bajo limpios y legibles.

Una pequeña estructura contribuye en gran medida a un lienzo limpio. Las siguientes recomendaciones ayudan al visor de código bajo a representar tu flujo de trabajo codificado como bloques de código bajo legibles en lugar de bloques de código opacos. Están ordenados por impacto, comenzando con los cambios más importantes.

Servicios de UiPath sobre código hecho a mano

Las llamadas a los servicios del proyecto (system.AddQueueItem(...), excel.ReadRange(...), mail.SendSmtp(...), uiAutomation.Click(...)) se renderizan como tarjetas de actividad enriquecidas: un nombre para mostrar amigable, el icono de servicio, propiedades editables y una variable de salida escrita.

La misma operación implementada desde cero, con HttpClient, System.IO o una biblioteca NuGet Excel, se representa en el mejor de los casos como una tarjeta de Asignación que contiene una expresión larga y en el peor de los casos como un bloque de código. Alcanzar primero los paquetes de actividades y pasar a C# personalizado solo cuando ninguna actividad cubre la necesidad, mantiene visible una mayor parte del flujo de trabajo.

// Renders as a "Write Range" activity card with editable properties:
excel.WriteRange("C:\\out.xlsx", "Sheet1", "A1", table);

// Renders as an opaque code block:
using var writer = new StreamWriter("C:\\out.csv");

El método de entrada como capa de orquestación

La vista de gráfico solo dibuja el método de entrada ([Workflow] o Execute). Cada llamada a uno de tus propios métodos se convierte en un único bloque etiquetado, y al seleccionarlo se profundiza en el ayudante.

Mantener la ramificación de nivel superior, los bucles y la gestión de errores en el método de entrada, y mover las secuencias de pasos detalladas a métodos privados bien nombrados, hace que el gráfico se lea como un flujo limpio de alto nivel — ValidateInvoice → PostToQueue → NotifyFinance, en lugar de un muro de tarjetas de bajo nivel. Cada ayudante también tiene su propia sección en la vista Flujo de trabajo, por lo que no hay nada oculto. Los nombres reveladores de intenciones importan doble aquí: el nombre del método es la etiqueta del bloque.

Flujo de control como declaraciones, no expresiones

El lienzo solo puede dibujar ramificaciones y bucles que existen en el nivel de declaración. La lógica escondida dentro de las expresiones (lambdas, cadenas de Language Integrated Query (LINQ), ternarios anidados o expresiones switch) se comprime en una sola tarjeta, lo que anula el propósito del visualizador.

Vale la pena tener en cuenta la distinción switch: una instrucción switch se renderiza completamente, como un contenedor Switch con un brazo por caso, mientras que la forma de expresión (var label = total switch { ... };) permanece comprimida dentro de una sola tarjeta Asignar. El formulario de declaración es la mejor opción cuando la ramificación es un paso del proceso que un lector debería ver.

// Invisible logic — one code block, the filtering and branching are not drawn:
invoices.Where(i => i.Amount > 1000).ToList().ForEach(i => Approve(i));

// Visible logic — a loop containing a decision containing an Invoke block:
foreach (var invoice in invoices)
{
    if (invoice.Amount > 1000)
    {
        Approve(invoice);
    }
}

Una frase ingeniosa de LINQ sigue estando bien cuando se trata de una simple proyección cuyos detalles ocultarías con gusto (var names = rows.Select(r => r.Name).ToList(); se renderiza como una tarjeta de Asignación). La regla general: si un lector del diagrama debe ver la ramificación, escríbela como if, switch o foreach.

Equivalentes renderizables para construcciones alternativas

Varias construcciones comunes recurren a los bloques de código. Cada uno tiene un equivalente renderizable que produce bloques visibles en su lugar.

En lugar de	Escribir	Porque
list.ForEach(x => ...)	foreach (var x in list)	El cuerpo se convierte en bloques visibles
Funciones locales	Métodos privados	Los métodos privados se representan como bloques Invocar navegables
using var handle = excel.UseWorkbook(...);	using (var handle = excel.UseWorkbook(...)) { ... }	El formulario de bloque se representa como un marco de ámbito y permite que las llamadas en su handle interior se resuelvan como actividades
int a = 1, b = 2;	Una declaración por línea	Cada una se convierte en su propia tarjeta Asignar
string result; ... result = ...; más tarde	Una declaración con un inicializador en el primer uso	Las declaraciones básicas recurren a los bloques de código

Declaraciones de variables en línea, una por declaración

Una declaración con un inicializador se representa como una tarjeta Asignar (o como la salida de una tarjeta de actividad) y alimenta el panel Variables por método. Una declaración simple se representa como un bloque de código. Declarar cada variable donde se produce su valor por primera vez lo mantiene visible.

var asset = system.GetAsset("Config");        // activity card, output: asset
int retryCount = 0;                            // Assign card, typed

Tipos explícitos en los que el espectador no puede inferirlos

El lienzo etiqueta cada variable de salida con el mejor tipo que puede encontrar:

• Para las llamadas de actividad reconocidas, el tipo proviene automáticamente de los metadatos del paquete. var asset = system.GetAsset(...) ya muestra el tipo de retorno real, por lo que var no cuesta nada allí.
• Para todo lo demás (asignaciones simples, llamadas a tus propios métodos y expresiones calculadas), var se muestra literalmente como var. Un tipo explícito pone el tipo real en la tarjeta y en el panel Variables.

var totals = ComputeTotals(rows);        // Variables panel shows: totals : var
DataTable totals = ComputeTotals(rows);  // Variables panel shows: totals : DataTable

Comentarios que describen la intención

Un comentario // colocado directamente encima de una actividad, llamada de método, if, foreach, for, switch, try, return o #region se adjunta a ese bloque. Se convierte en la descripción de la tarjeta en la vista de Gráfico, la información sobre herramientas de la fila en la vista de Flujo de trabajo y el campo Descripción en el panel de propiedades. Se unen las líneas de comentario consecutivas.

// High-value invoices need manual approval before posting
system.AddQueueItem("InvoiceApproval", reference: invoice.Id);

Los comentarios que no se encuentran por encima de una declaración de este tipo se representan como sus propias filas de código pequeñas, por lo que un comentario útil por paso se lee mejor que los comentarios dispersos.

Fases del proceso agrupadas con regiones

#region Name ... #endregion se representa como un grupo colapsable con nombre en ambas vistas, y las regiones pueden anidarse. Cuando las regiones llevan el nombre de las fases empresariales Login, Process invoices, Reporting, un gráfico contraído se lee como un resumen de proceso, y expandir una región revela sus pasos.

Asignaciones relacionadas agrupadas

Dos o más asignaciones consecutivas se pliegan en una sola tarjeta de asignación múltiple. Inicializar valores relacionados en una ejecución ininterrumpida los mantiene en una tarjeta ordenada en lugar de dispersarlos por el flujo. Por el contrario, una asignación que merezca su propia tarjeta debe diferenciarse de otras asignaciones.

Una llamada por declaración

Cuando las llamadas están encadenadas (row.GetValue("col").ToString().Trim()), el espectador solo puede mostrar la cadena como una sola fila, y las cadenas en receptores no reconocidos retroceden por completo. Dividir una cadena significativa en pasos con variables intermedias con nombre da a cada paso su propio bloque. Para las API de identificadores, como los libros de Excel y las carpetas de correo, también permite al espectador realizar un seguimiento del identificador para que las llamadas de seguimiento se rendericen como actividades adecuadas.

Invocaciones de flujo de trabajo reconocibles

• workflows.MyOtherWorkflow(arg1, arg2) se renderiza como una tarjeta Invocar flujo de trabajo dedicada, con cada argumento identificado por dirección (In, Out o InOut) y navegación al archivo de flujo de trabajo.
• SharedHelpers.Method(...) llama a otro archivo .cs del proyecto renderizado como bloques Invocar navegables. Mantenerlos como una sola llamada por instrucción, en lugar de como parte de una cadena más larga, es lo que permite resolverlos.

Lista de verificación rápida

• Los pasos utilizan servicios de actividad (system., excel., mail. y similares), no equivalentes manuales.
• El método [Workflow] es corto y orquesta métodos privados bien nombrados.
• La ramificación y el bucle son declaraciones (if, switch, foreach, for, while, try), sin lógica oculta en lambdas o procesos LINQ.
• Las variables se declaran en línea, una por declaración, con un inicializador.
• Los tipos explícitos se utilizan cuando el espectador no puede inferir uno, como los resultados del método auxiliar y los valores calculados.
• Un comentario de una línea // se encuentra encima de cada paso significativo.
• Las fases del proceso están envueltas en #region.
• Cada declaración contiene una llamada de servicio o ayudante, sin cadenas largas.
• Otros flujos de trabajo se invocan a través de workflows.X(...).
• No quedan tarjetas de bloque de código grises en el lienzo: cada una es un punto donde la vista visual se ha quedado ciega.

Contenido relacionado

• Visor de código bajo
• Introducción a las automatizaciones codificadas
• Mejores prácticas