Como Criar Regras do Analisador de Fluxo de Trabalho

O Analisador de Fluxo de Trabalho é uma ferramenta para garantir que seu projeto siga os requisitos de práticas recomendadas, manutenção, legibilidade, desempenho, reusabilidade e segurança.

Esses conceitos são importantes para garantir fluxos de trabalho simples e confiáveis, que podem resumir projetos de automação de grande porte.

Observação: para criar regras personalizadas, você precisa do pacote UiPath.Activities.Api , localizado no feed Oficial . O pacote SDK deve ser usado como uma dependência de desenvolvimento no seu projeto personalizado. Leia mais sobre Dependências de desenvolvimento.

Assista ao vídeo abaixo para obter instruções passo a passo sobre como criar regras personalizadas e como criar atividades personalizadas com a extensão Usando o criador de atividades .

No seu formato padronizado, o Analisador de Fluxo de Trabalho é integrado no Studio e incorpora os recursos de validação e analisador. Não é possível analisar se a validação retornar erros.

Conceitos do Analisador de Fluxo de Trabalho

Para criar regras personalizadas para seu projeto, alguns conceitos devem ser definidos, a fim de entender melhor como o Analisador de Fluxo de Trabalho funciona nos bastidores.

Observação:

When building custom rules, target the .NET version depending on the version of Studio and the project compatibility:

• Studio 2021.4 e anteriores: .NET Framework 4.6.1.
• Studio 2021.10.6 and later: .NET Framework 4.6.1 for Windows-legacy projects, .NET 6 for Windows and cross-platform projects.

Regras e contadores

O Analisador de Fluxo de Trabalho usa alguns critérios para garantir que a confiabilidade do projeto seja cumprida. Essas verificações são executadas usando regras e contadores que foram cuidadosamente definidos.

Uma regra representa um requisito que deve ser cumprido. Ela pode ser definida para verificar se o objeto de inspeção cumpre a definição da regra.

Um contador representa uma verificação feita para revelar quantas vezes um evento ou condição específica ocorreu.

Para cada regra não cumprida, uma mensagem é adicionada ao painel Lista de erros no formato de um aviso, erro, informações ou mensagens detalhadas. Essas listas também contêm recomendações para fazer alterações e garantir que as regras sejam cumpridas.

Observação: ao criar regras e contadores personalizados, recomendamos seguir a convenção de nomenclatura detalhada na página Sobre o Workflow Analyzer .

Objeto de inspeção

O Analisador de Fluxo de Trabalho é capaz de executar uma análise detalhada de um objeto predefinido. O objeto representa o escopo a ser analisado, a área na qual a regra ou o contador deve ser imposto.

• Atividade: é o menor objeto de inspeção. Por exemplo, Convenção de Nomenclatura das Variáveis , Comprimento da Variável Excedido e Estatísticas das Atividades do Arquivo são três regras prontas para uso que podem ser definidas para inspecionar atividades.
• Fluxo de trabalho: as regras ou os contadores podem ser definidos para realizar as verificações em apenas um único arquivo de projeto. Contagem Alta de Argumentos e Sequência Vazia são apenas duas regras predefinidas que têm o fluxo de trabalho como escopo.
• Projeto: as verificações são realizadas no nível do projeto, garantindo que a confiabilidade do projeto seja cumprida. Dependências Não Utilizadas é uma regra aplicada no escopo do projeto.

Criação de regras

From the Official feed (https://pkgs.dev.azure.com/uipath/Public.Feeds/_packaging/UiPath-Official/nuget/v3/index.json), install the UiPath.Activities.Api package.

Para ajudar você a criar uma regra personalizada, vamos analisar uma regra predefinida atual no Analisador de Fluxo de Trabalho, Comprimento da Variável Excedido. Essa regra verifica se o comprimento das variáveis definidas no projeto é menor que 20 caracteres. O objeto de inspeção da regra é a atividade.

Nos bastidores, a regra é semelhante a isto:

// This static class is not mandatory. It just helps organizining the code.
internal static class VariableLengthRule
    {
  // This should be as unique as possible, and should follow the naming convention.
        private const string RuleId = "ST-NMG-008";
        internal static Rule<IActivityModel> Get()
        {
            var rule = new Rule<IActivityModel>("Variable Length Rule", RuleId, Inspect)
            {
                RecommendationMessage = Recommendation,
              /// Off and Verbose are not supported.
                ErrorLevel = System.Diagnostics.TraceLevel.Warning
            };
            return rule;
        }
  
              // This is the function that executes for each activity in all the files. Might impact performance.
        // The rule instance is the rule provided above which also contains the user-configured data.
                  private static InspectionResult Inspect(IActivityModel activityModel, Rule ruleInstance)
        {
            var messageList = new List<string>();
            foreach(var activityModelVariable in activityModel.Variables)
            {
                if (activityModelVariable.DisplayName.Length > 20)
                {
                    messageList.Add($"The variable {activityModelVariable.DisplayName} has a length longer than 20");
                }
            }
            if (messageList.Count > 0)
            {
                return new InspectionResult()
                {
                    ErrorLevel = ruleInstance.ErrorLevel,
                    HasErrors = true,
                    RecommendationMessage = ruleInstance.RecommendationMessage,
                  // When inspecting a model, a rule can generate more than one message.
                    Messages = messageList
                };
            }
            else
            {
                return new InspectionResult() { HasErrors = false };
            }
        }
    }

O parâmetro RuleId requer o nome da sua regra. Neste exemplo, a regra Comprimento da Variável Excedido traz o ID da regra ST-NMG-008 e segue a Convenção de Nomenclatura das Regras. Observe que a convenção de nomenclatura usada pelas regras disponíveis por padrão no Studio não é obrigatória.

O parâmetro RecommendationMessage requer que uma mensagem seja exibida como recomendação, para ajudar o usuário a resolver as inconsistências encontradas após a análise ser concluída. A mensagem deve ser sucinta e fornecer etapas claras.

O parâmetro ErrorLevel indica a ação padrão a ser executada, caso a condição não seja cumprida. Neste exemplo, a regra retorna um aviso. As ações padrão podem ser erro, aviso, informações ou mensagem detalhada.

Como criar regras com parâmetros

A situação muda um pouco quando queremos criar regras que contenham parâmetros personalizáveis. Uma dessas regras é a Convenção de Nomenclatura das Variáveis. Seu elemento de inspeção é a atividade e traz uma expressão Regex padrão, que pode ser alterada.

Nos bastidores, essa regra é semelhante a isto:

internal static class VariableNamingRule
    {
        private const string RuleId = "ST-NMG-001";
        private const string RegexKey = "Regex";
        private const string DefaultRegex = @"^([A-Z]|[a-z])+([0-9])*$";
        internal static Rule<IActivityModel> Get()
        {
            var rule = new Rule<IActivityModel>(Strings.ST_NMG_001_Name, RuleId, Inspect)
            {
                RecommendationMessage = Recommendation,
                ErrorLevel = System.Diagnostics.TraceLevel.Warning
            };
            rule.Parameters.Add(RegexKey, new Parameter()
        }
                                
       private static InspectionResult Inspect(IActivityModel activityModel, Rule ruleInstance) 
        {
          // This retrieves the parameter value from the rule instance as configured by the user, if not, the default value.
            var setRegexValue = ruleInstance.Parameters[RegexKey]?.Value;
          
            var regex = new Regex(setRegexValue);
            var messageList = new List<string>();
            foreach (var activityModelVariable in activityModel.Variables)
            {
                if(!regex.IsMatch(activityModelVariable.DisplayName))
                {
                    messageList.Add(string.Format(Strings.ST_NMG_001_ErrorFormat, activityModelVariable.DisplayName, setRegexValue));
                }
            }
            if(messageList.Count > 0)
            {
                return new InspectionResult()
                {
                    ErrorLevel = ruleInstance.ErrorLevel,
                    HasErrors = true,
                    RecommendationMessage = ruleInstance.RecommendationMessage,
                    Messages = messageList
                };
            }
            else
            {
                return new InspectionResult() { HasErrors = false };
            }
        }
    }

Observe que ela chama RuleId, RegexKey e DefaultRegex, que é a expressão Regex padrão associada a essa regra.

Os parâmetros RecommendationMessage e ErrorLevel são os mesmos da regra apresentada anteriormente.

Como criar contadores

Os contadores representam as verificações feitas para revelar quantas vezes um evento ou uma condição específica ocorreu.

A estrutura é um pouco diferente das regras, no sentido que o único parâmetro ErrorLevel disponível para os contadores é Info. Portanto, a expressão para definir o nível de erro para um contador deve ser semelhante a isto ErrorLevel = System.Diagnostics.TraceLevel.Info.

Vamos considerar Estatísticas das Atividades do Arquivo como um exemplo de como as regras de contadores se parecem nos bastidores:

internal static class NumberOfActivitiesInFile
    {
        private const string RuleId = "ST-ANA-009";
        internal static Counter<IActivityModel> Get()
        {
            return new Counter<IActivityModel>(Strings.ST_ANA_009_Name, RuleId, Inspect);
        }
  
  // A Counter<T> receives the entire collection of T objects in the parent structure. e.g. activities in workflow, workflows in project.
  private static InspectionResult Inspect(IReadOnlyCollection<IActivityModel> activities, Counter ruleInstance)
        {
            return new InspectionResult()
            {
              // For a counter, the error level is always info, even if not set here.
                ErrorLevel = System.Diagnostics.TraceLevel.Info,
              // For a counter, the Has Errors field is always ignored.
                HasErrors = false,
                Messages = new List<string>() { string.Format(Strings.ST_ANA_009_ErrorFormat,  activities.Count) }
            };
        }

Como criar regras para o StudioX

Por padrão, as regras se aplicam apenas ao perfil do Studio. Para fazer com que uma regra apareça no perfil do StudioX também, adicione a propriedade ApplicableScopes e configure-a para incluir BusinessRule. Por exemplo, você pode adicionar a propriedade assim:

var rule = new Rule<IActivityModel>(Strings.ORG_USG_001_Name, RuleId, Inspect)
            {
                RecommendationMessage = Strings.ORG_USG_001_Recommendation,
                ErrorLevel = TraceLevel.Error,
                //Must contain "BusinessRule" to appear in StudioX, rules always appear in Studio
                ApplicableScopes = new List<string> { RuleConstants.BusinessRule }
            };

Registro de regras

Método da interface de registro

Lembre-se de que ao usar esse método, seu pacote é compatível apenas com as versões 2019.10 ou posteriores do Studio.

Implemente a interface IRegisterAnalyzerConfiguration com o seguinte método Initialize(IAnalyzerConfigurationService workflowAnalyzerConfigService).

using UiPath.Studio.Activities.Api;
using UiPath.Studio.Activities.Api.Analyzer;
using UiPath.Studio.RulesLibrary.Rules.Naming;
namespace UiPath.Studio.RulesLibrary
{
    public class RegisterAnalyzerConfiguration : IRegisterAnalyzerConfiguration
    {
        public void Initialize(IAnalyzerConfigurationService workflowAnalyzerConfigService)
        {
            // Naming
            workflowAnalyzerConfigService.AddRule(VariableNamingRule.Get());
            workflowAnalyzerConfigService.AddRule(DisplayNameDuplicationRule.Get());
            workflowAnalyzerConfigService.AddRule(VariableNameDuplicationRule.Get());
            workflowAnalyzerConfigService.AddRule(ArgumentNamingRule.Get());
            workflowAnalyzerConfigService.AddRule(VariableLengthRule.Get());
        }
    }
}

Observação: chame o método HasFeature na IAnalyzerConfigurationService para registrar as regras para uma versão específica do Studio.

Método IRegisterMetadata

Observe que esse método está disponível apenas para as versões 2019.6 ou posteriores do Studio, e ele não é adequado como o método da interface de registro.

• Adicione um método void Initialize(object api) à sua implementação de IRegisterMetadata.
• Na sua implementação Initialize, converta o parâmetro object para WorkflowDesignApi, e adicione tudo sob uma atividade Try Catch, apenas para garantir que as exceções sejam gerenciadas.
• Depois de resolver o WorkflowDesignApi, o WorkflowAnalyzerConfigService fica disponível como uma propriedade.
• Neste momento, você tem acesso ao IAnalyzerConfigurationService detalhado na seção acima.

Como adicionar regras ao Studio

As regras personalizadas do Analisador de Fluxo de Trabalho podem ser integradas no Studio de duas maneiras:

• No nível global, adicionando o assembly externo (.dll) no local de instalação do Studio.
• No nível do projeto, instalando o pacote de atividades personalizadas.

No nível global

Para tornar as regras personalizadas disponíveis em todos os projetos criados na sua instância do Studio, você deve adicionar os pacotes de assembly externo (.dll) a uma pasta específica, a partir da qual o Studio carrega as regras personalizadas. Por padrão, o caminho da pasta é:

• Nas versões do Studio anteriores à 2021.10:

  • For per-machine installations: %ProgramFiles%\UiPath\Studio\Rules
  • Para instalações por usuário: %LocalAppData%\Programs\UiPath\Studio\Rules

• No Studio 2021.10.6 e posterior:

  • For per-machine installations: %ProgramFiles%\UiPath\Studio\Rules\net6.0 (for rules targetting Windows and cross-platform projects) and %ProgramFiles%\UiPath\Studio\net461\Rules (for rules targetting Windows-legacy projects)
  • For per-user installations: %LocalAppData%\Programs\UiPath\Studio\Rules\net6.0 (for rules targetting Windows and cross-platform projects) and %LocalAppData%\Programs\UiPath\Studio\net461\Rules (for rules targetting Windows-legacy projects)

Opcionalmente, você pode alterar a pasta a partir da qual o Studio carrega as regras personalizadas acessando Início (Modo de exibição Backstage do Studio) > Configurações > Locais e definindo um local de regras personalizadas do Analisador de Fluxo de Trabalho . Essa funcionalidade está disponível no Studio v2020.10. e posterior.

Siga os passos detalhados na página Criando uma atividade personalizada para exportar o código como um arquivo arquivo .xaml.

No nível do projeto

Para disponibilizar regras personalizadas apenas para um determinado projeto, crie um pacote NuGet (.nupkg) e o instale em um projeto do Studio como uma dependência.