Escrevendo fluxos de trabalho codificados compatíveis com a tela

Recomendações para estruturar fluxos de trabalho codificados para que o Visualizador de pouco código os renderize como diagramas de pouco código limpos e legíveis.

Um pouco de estrutura ajuda muito em uma tela limpa. As recomendações abaixo ajudam o Visualizador de pouco código a renderizar seu fluxo de trabalho codificado como blocos de pouco código legíveis em vez de blocos de código opacos. Elas são ordenadas por impacto, começando pelas alterações mais importantes.

Serviços da UiPath sobre código programado manualmente

Chamadas para os serviços do projeto — system.AddQueueItem(...), excel.ReadRange(...), mail.SendSmtp(...), uiAutomation.Click(...) — renderizadas como cartões de atividades avançados: um nome de exibição amigável, o ícone do serviço, propriedades editáveis e uma variável de saída digitada.

A mesma operação implementada do zero — com HttpClient, System.IO ou uma biblioteca do NuGet Excel — é renderizada, no melhor dos casos, como um cartão Atribuir contendo uma expressão longa, e no pior dos casos, como um bloco de código. Alcançar os pacotes de atividades primeiro e soltar no C# personalizado apenas onde nenhuma atividade cobrir a necessidade, mantém mais o fluxo de trabalho visível.

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

O método de entrada como uma camada de orquestração

A visualização do Gráfico desenha apenas o método de entrada ([Workflow] ou Execute). Cada chamada para um de seus próprios métodos torna-se um único bloco rotulado e, ao selecioná-lo, detalha o auxiliar.

Manter a ramificação de nível superior, loops e tratamento de erros no método de entrada e mover sequências de etapas detalhadas para métodos privados bem nomeados, faz com que o gráfico seja lido como um fluxo limpo e de alto nível — ValidateInvoice → PostToQueue → NotifyFinance — em vez de uma barreira de cartões de baixo nível. Cada auxiliar também recebe sua própria seção na visualização do fluxo de trabalho, portanto, nada fica oculto. Os nomes que revelam a intenção importam dobro aqui: o nome do método é o rótulo do bloco.

Controle o fluxo como instruções, não expressões

A tela só pode desenhar ramificações e loops que existem no nível da instrução. A lógica oculta dentro de expressões — lambdas, cadeias de Consultas Integradas a Idiomas (linQ), ternários aninhados ou expressões switch — é compactada em um único cartão, que anula o propósito do visualizador.

Vale a pena notar a distinção: uma switch switch instrução é renderizada totalmente, como um contêiner Switch com um robô por caso, enquanto o formulário de expressãovar label = total switch { ... }; () permanece compactado dentro de um único cartão Assign. O formulário de instrução é a melhor escolha quando a ramificação é uma etapa do processo que o leitor deve 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);
    }
}

Um One-liner linQ ainda é adequado quando é uma planilha simples cujos detalhes você ocultaria felizmente (var names = rows.Select(r => r.Name).ToList(); é renderizado como um cartão Atribuir). A regra geral: se um leitor do diagrama ver a ramificação, escreva-a como if, switch ou foreach.

Equivalentes renderizáveis para construções de fallback

Várias construções comuns retornam a blocos de código. Cada um tem um equivalente renderizável que produz blocos visíveis.

Em vez de	Gravar	Porque
list.ForEach(x => ...)	foreach (var x in list)	O corpo se torna blocos visíveis
Funções locais	Métodos privados	Métodos privados renderizados como blocos navegáveis Invoke
using var handle = excel.UseWorkbook(...);	using (var handle = excel.UseWorkbook(...)) { ... }	O formulário de bloco é renderizado como um quadro de escopo e permite que as chamadas em handle dentro dele sejam resolvidas como atividades
int a = 1, b = 2;	Uma declaração por linha	Cada um se torna seu próprio cartão Atribuir
string result; ... result = ...; depois	Uma declaração com um inicializador no primeiro uso	Declarações vazias retornam a blocos de código

Declarações de variáveis embutidas, uma por instrução

Uma declaração com um inicializador é renderizada como um cartão Atribuir (ou como a saída de um cartão de atividade) e alimenta o painel Variáveis por método. Uma declaração bruta é renderizada como um bloco de código. Declarar cada variável onde seu valor é produzido pela primeira vez a mantém visível.

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

Tipos explícitos em que o visualizador não pode inferi-los

A tela rotula cada variável de saída com o melhor tipo que ela pode encontrar:

• Para chamadas de atividade reconhecidas, o tipo vem dos metadados do pacote automaticamente. var asset = system.GetAsset(...) já exibe o tipo de retorno real, então var não custa nada lá.
• Para todo o resto — atribuições simples, chamadas para seus próprios métodos e expressões computadas — var exibe literalmente como var. Um tipo explícito coloca o tipo real no cartão e no painel Variáveis.

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

Comentários que descrevem a intenção

Um comentário // colocado diretamente acima de uma atividade, chamada de método, if, foreach, for, switch, try, return, ou #region estiver anexado a esse bloco. Ele se torna a descrição do cartão na visualização do Gráfico, a dica de ferramenta de linha na visualização do Fluxo de Trabalho e o campo Descrição no painel de propriedades. Linhas de comentário consecutivas são unidas.

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

Os comentários que não ficam acima de uma instrução desse tipo são renderizados como suas próprias linhas de código pequenas, portanto, um comentário proposital por etapa é lido melhor do que comentários distribuídos.

Fases do processo agrupadas por regiões

#region Name ... #endregion é renderizado como um grupo recolhível nomeado em ambas as exibições, e as regiões podem aninhar-se. Quando as regiões são nomeadas após fases de negócios — Login, Process invoices, Reporting — um gráfico recolhido é lido como um resumo do processo, e a expansão de uma região revela suas etapas.

Atribuições relacionadas agrupadas

Duas ou mais atribuições consecutivas são dobradas em um único cartão de Atribuição Múltipla. A inicialização de valores relacionados em uma execução ininterrupta os mantém em um cartão organizado em vez de distribuí-los pelo fluxo. Por outro lado, uma atribuição que merece seu próprio cartão deve se destacar de outras atribuições.

Uma chamada por instrução

Quando as chamadas são encadeadas (row.GetValue("col").ToString().Trim()), o visualizador só pode exibir a cadeia como uma única linha, e as cadeias em receptores não reconhecidos falham completamente. Dividir uma cadeia significativa em etapas com variáveis intermediárias nomeadas dá a cada etapa seu próprio bloco. Para APIs de identificação, como pastas de trabalho do Excel e pastas de email, também permite que o visualizador rastreie o identificador para que as chamadas de acompanhamento sejam renderizadas como atividades adequadas.

Invocações de fluxo de trabalho reconhecíveis

• workflows.MyOtherWorkflow(arg1, arg2) renderiza como um cartão Invoke Workflow dedicado, com cada argumento rotulado pela direção (In, Out ou InOut) e navegação até o arquivo do fluxo de trabalho.
• SharedHelpers.Method(...) chama em outro arquivo .cs do projeto renderizado como blocos navegáveis Invoke. Mantê-los como uma única chamada por instrução, em vez de fazer parte de uma cadeia mais longa, é o que permite que eles sejam resolvidos.

Lista de verificação rápida

• As etapas usam serviços de atividades (system., excel., mail. e semelhantes), não equivalentes rolados manualmente.
• O [Workflow] método é curto e orquestra métodos privados bem nomeados.
• A ramificação e o loop são instruções (if, switch, foreach, for, while, try), sem lógica oculta em lambdas ou pipelines linQ.
• As variáveis são declaradas em linha, uma por instrução, com um inicializador.
• Tipos explícitos são usados quando o visualizador não pode inferir um, como resultados do método auxiliar e valores computados.
• Um // comentário de uma linha fica acima de cada etapa significativa.
• As fases do processo são envolvidas por #region.
• Cada instrução contém uma chamada de serviço ou auxiliar, sem cadeias longas.
• Outros fluxos de trabalho são invocados por meio workflows.X(...) de.
• Nenhum cartão de bloco de código cinza é deixado na tela — cada um é um local onde a visualização visual ficou oculta.

Conteúdo relacionado

• Visualizador de pouco código
• Introdução de automações codificadas
• Melhores práticas