Écrire des workflows codés conviviaux

Recommandations pour structurer les workflows codés afin que la visionneuse low-code les restitue sous forme de diagrammes low-code propres et lisibles.

Un peu de structure fait un long chemin vers une zone de dessin propre. Les recommandations ci-dessous aident la visionneuse low-code à restituer votre workflow codé sous forme de blocs low-code lisibles au lieu de blocs de code sombres. Elles sont triées par impact, en commençant par les modifications qui comptent le plus.

Services UiPath via du code déroulant

Appels aux services du projet — system.AddQueueItem(...), excel.ReadRange(...), mail.SendSmtp(...), uiAutomation.Click(...) — rendus sous forme de cartes d'activité enrichies: un nom complet convivial, l'icône de service, des propriétés modifiables et une variable de sortie saisie.

La même opération implémentée à partir de zéro — avec HttpClient, System.IO ou une bibliothèque NuGet Excel — s'affiche au mieux comme une carte Assign contenant une longue expression, et au pire sous forme d'un bloc de code. Le fait d'atteindre les packages d'activités en premier et de passer au C# personnalisé uniquement lorsqu'aucune activité ne couvre le besoin vous permet de garder la plus grande partie du workflow visible.

// 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");

La méthode d’entrée en tant que couche d’orchestration

La vue Graphique affiche uniquement la méthode d'entrée ([Workflow] ou Execute). Chaque appel à l'une de vos propres méthodes devient un seul bloc étiqueté, et sa sélection permet d'explorer l'assistant.

En conservant la ramification de niveau supérieur, les boucles et la gestion des erreurs dans la méthode d'entrée et en déplaçant des séquences d'étapes détaillées dans des méthodes privées bien nommées, le graphique est lu comme un flux propre et de haut niveau — ValidateInvoice → PostToQueue → NotifyFinance — au lieu d'un tableau de cartes de faible niveau. Chaque assistant dispose également de sa propre section dans la vue Workflow, donc rien n’est masqué. Les noms qui montrent l'intention sont doubles ici: le nom de la méthode est le libellé du bloc.

Flux de contrôle sous forme d'instructions, et non d'expressions

La zone de dessin ne peut dessiner que le branchement et la boucle qui existent au niveau de l'instruction. La logique contenue dans les expressions — lambdas, chaînes Language Integration Query, ternes imbriquées ou switch expressions — est compressée dans une seule carte, ce qui va à l'encontre de l'objectif du visualiseur.

Il convient de noter la distinction switch: une instruction switch s’affiche entièrement sous la forme d’un conteneur Switch avec une branche par cas, tandis que la forme de l’expression (var label = total switch { ... };) reste compressée dans une seule carte Assign. La forme de l'instruction est le meilleur choix lorsque la ramification est une étape de processus qu'un lecteur doit voir.

// 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);
    }
}

Une ligne linq est toujours utilisable lorsqu’il s’agit d’une simple projection dont vous masqueriez les détails (var names = rows.Select(r => r.Name).ToList(); se présente sous la forme d’une carte Attribuer). La règle de la miniature: si un lecteur du diagramme doit voir la ramification, écrivez-la sous la forme if, switch ou foreach.

Équivalents affichables pour les constructions de secours

Plusieurs constructions courantes sont des blocs de code. Chacun a un équivalent restituable qui produit des blocs visibles à la place.

Au lieu de	Écrire	Parce que
list.ForEach(x => ...)	foreach (var x in list)	Le corps devient des blocs visibles
Fonctions locales	Méthodes privées	Les méthodes privées s'affichent sous forme de blocs d'appel navigables
using var handle = excel.UseWorkbook(...);	using (var handle = excel.UseWorkbook(...)) { ... }	Le formulaire de bloc s'affiche sous la forme d'un cadre d'étendue et permet aux appels sur handle à l'intérieur de se résoudre en tant qu'activités
int a = 1, b = 2;	Une déclaration par ligne	Chacun devient sa propre carte d’attribution
string result; ... result = ...; ultérieurement	Une déclaration avec un initialiseur lors de la première utilisation	Les déclarations à barres retournent aux blocs de code

Déclarations de variables en ligne, une par instruction

Une déclaration avec un initialisateur se présente sous la forme d’une carte Affecter (ou comme la sortie d’une carte d’activité) et alimente le panneau Variables par méthode. Une déclaration à barres se présente sous la forme d'un bloc de code. La déclaration de chaque variable où sa valeur est d'abord produite la rend visible.

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

Types explicites que la visionneuse ne peut pas déduire

Le canevas labellise chaque variable de sortie avec le meilleur type qu'il peut trouver:

• Pour les appels d’activité reconnus, le type est automatiquement fourni dans les métadonnées du package. var asset = system.GetAsset(...) affiche déjà le type de retour réel, donc var ne coûte rien.
• Pour tout le reste - affectations simples, appels à vos propres méthodes et expressions calculées - var s'affiche littéralement comme var. Un type explicite place le type réel sur la carte et dans le panneau Variables.

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

Commentaires représentatifs de l'intention

Un commentaire // placé directement au-dessus d'une activité, d'un appel de méthode, if, foreach, for, switch, try, return, ou #region est attaché à ce bloc. Elle devient la description de la carte dans la vue Graphique, l’info-bulle de la ligne dans la vue Workflow et le champ Description dans le panneau Propriétés. Les lignes de commentaires consécutives sont jointes.

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

Les commentaires qui ne se trouvent pas au-dessus d'une telle instruction s'affichent comme leurs propres petites lignes de code, de sorte qu'un commentaire utile par étape se lit mieux que des commentaires éparsus.

Phases de processus regroupées avec des régions

#region Name ... #endregion s'affiche sous la forme d'un groupe nommé et réductible dans les deux vues, et les régions peuvent imbriquer. Lorsque les régions sont nommées d'après les phases métier — Login, Process invoices, Reporting — un graphique réduit se lit comme un résumé de processus, et le développement d'une région révèle ses étapes.

Tâches connexes regroupées

Deux affectations consécutives ou plus sont regroupées dans une seule carte d'affectation multiple. L'initialisation des valeurs associées dans une exécution ininterrompue les conserve dans une même carte de conservation au lieu de les répartir dans le flux. Inversement, une affectation qui méritent sa propre carte doit se distinguer des autres affectations.

Un appel par instruction

Lorsque les appels sont enchaînés (row.GetValue("col").ToString().Trim()), l'observateur ne peut faire apparaître la chaîne que sous la forme d'une seule ligne, et les chaînes sur les récepteurs non reconnus se replient entièrement. La division d'une chaîne significative en étapes avec des variables intermédiaires nommées donne à chaque étape son propre bloc. Pour les API de gestion, telles que les classeurs Excel et les dossiers de messagerie, il permet également à la visionneuse de suivre le handle afin que les appels de suivi soient rendus comme des activités appropriées.

Invocations de workflow identifiables

• workflows.MyOtherWorkflow(arg1, arg2) s'affiche sous la forme d'une carte Appeler le workflow dédiée, avec chaque argument badgé par direction (Entrée, Sortie ou EntréeSortie) et la navigation vers le fichier de workflow.
• Les appels SharedHelpers.Method(...) dans un autre fichier .cs du projet s'affichent sous forme de blocs d'invocation navigables. Les conserver sous forme d'un seul appel par instruction, plutôt que de faire partie d'une chaîne plus longue, est ce qui leur permet de se résoudre.

Liste de contrôle rapide

• Les étapes utilisent des services d'activité (system., excel., mail. et similaires), et non des équivalents lancés à la main.
• La méthode [Workflow] est courte et orchestre des méthodes privées bien nommées.
• Les branches et les boucles sont des instructions (if, switch, foreach, for, while, try), sans logique cachée dans les lambdas ou les pipelines linQ.
• Les variables sont déclarées en ligne, une par instruction, avec un initialiseur.
• Les types explicites sont utilisés lorsque l'observateur ne peut pas en déduire un, tels que les résultats de la méthode d'assistance et les valeurs calculées.
• Un commentaire // en une ligne précède chaque étape significative.
• Les phases de processus sont encapsulées dans #region.
• Chaque instruction contient un appel de service ou d’aide, sans chaînes longues.
• Les autres workflows sont appelés via workflows.X(...).
• Aucune carte de bloc de code grise ne reste sur le canevas - chacune est un endroit où la vue visuelle est masquée.

Contenu associé

• Visionneuse low-code
• Introduction aux automatisations codées
• Meilleures pratiques