Création de règles d'analyse de flux de travail

L'analyseur de workflow est un outil permettant de s'assurer que votre projet respecte les meilleures pratiques en matière de maintenabilité, de lisibilité, de performances, de réutilisation, de fiabilité et de sécurité.

Ces concepts sont importants pour garantir des workflows propres et fiables pouvant résumer de grands projets d'automatisation.

Remarque : pour créer des règles personnalisées, vous avez besoin du package UiPath.Activities.Api du flux Official . Le package SDK doit être utilisé comme dépendance de développement dans votre projet personnalisé. En savoir plus sur Dépendances de développement.

Regardez la vidéo ci-dessous pour obtenir des instructions étape par étape sur la création de règles personnalisées et sur la création d'activités personnalisées avec l'extension Utilisation du créateur d'activités .

Sous sa forme standard, l'analyseur de workflow est intégré à Studio et intègre des fonctionnalités de validation et d’analyseur. L'analyse ne peut pas être effectuée si la validation renvoie des erreurs.

Concepts de l'analyseur de workflow

Afin de créer des règles personnalisées pour votre projet, un certain nombre de concepts doivent être définis pour mieux comprendre le fonctionnement en arrière-plan de l'analyseur de workflow.

Remarque :

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

• Studio 2021.4 et versions antérieures : .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.

Règles et compteurs

L'analyseur de workflow utilise certains critères pour garantir la fiabilité du projet. Ces vérifications sont effectuées à l'aide de règles et de compteurs correctement définis.

Une règle représente une exigence devant être respectée. Elle peut être configurée pour vérifier l'objet d'inspection par rapport à la définition de la règle.

Un compteur représente une vérification effectuée pour indiquer le nombre de fois où un événement ou une condition spécifique s'est produit.

Pour chaque règle non satisfaite, un message est répertorié dans le panneau Liste d'erreurs sous la forme de messages d'avertissement, d'erreur, d'information ou de logs détaillés. Ces listes contiennent également des recommandations pour apporter des modifications et garantir le respect des règles.

Remarque : lors de la création de règles et de compteurs personnalisés, nous vous recommandons de suivre la convention d'affectation de noms détaillée à la page À propos de l'analyseur de workflow ( About Workflow Analyzer) .

Objet d'inspection

L'analyseur de workflow est capable d'effectuer une analyse en profondeur d'un objet prédéfini. L'objet représente l'étendue à analyser, la zone dans laquelle la règle ou le compteur est appliqué.

• Activité (Activity) : il s'agit de l'objet d'inspection le plus petit. Par exemple, Conventions d'affectation de noms des variables (Variables Naming Convention), Longueur de variable dépassée (Variable Length Exceeded) et Statistiques des activités du fichier (File Activities Stats) sont trois règles prêtes à l'emploi qui peuvent être définies pour inspecter des activités.
• Workflow (Workflow) : les règles ou les compteurs peuvent être définis pour effectuer des vérifications dans un fichier de projet unique. Nombre élevé d'arguments (High Arguments Count) et Séquence vide (Empty Sequence) sont simplement deux règles prédéfinies dont le workflow constitue l'étendue.
• Projet (Project) : des vérifications sont effectuées au niveau du projet, tout en garantissant que la fiabilité est satisfaite. Dépendances inutilisées (Unused Dependencies) est une règle appliquée dans le cadre du projet.

Création de règles

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.

Pour vous aider à créer une règle personnalisée, examinons une règle prédéfinie actuelle dans l'analyseur de workflow, Longueur de variable dépassée (Variable Length Exceeded). Cette règle vérifie si la longueur des variables définie dans le projet est inférieure à 20 caractères. L'objet d'inspection de la règle est activité.

En arrière-plan, la règle ressemble à ceci :

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

Le paramètre RuleId requiert le nom de votre règle. Dans cet exemple, la règle Variable Length Exceeded porte l'ID de règle ST-NMG-008 et suit la Rule Naming Convention. Notez que la convention d'affectation de nom utilisée par les règles disponibles par défaut dans Studio n'est pas obligatoire.

Le paramètre RecommendationMessage nécessite l'affichage d'un message en tant que recommandation pour aider l'utilisateur à résoudre des incohérences trouvées à la fin de l'analyse. Le message doit être succinct et offrir des étapes claires.

Le paramètre ErrorLevel indique la mesure par défaut à prendre au cas où la condition est pas remplie. Dans cet exemple, la règle génère un avertissement. Les actions par défaut peuvent être erreur, avertissement, information ou logs détaillés.

Créer des règles avec des paramètres

La situation change légèrement lorsque nous souhaitons créer des règles contenant des paramètres personnalisables. L'une de ces règles est Conventions d'affectation de noms des variables (Variables Naming Convention). Son élément d'inspection est activité et comporte une expression Regex par défaut, qui est modifiable.

En arrière-plan, cette règle ressemble à ceci :

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

Notez qu'il appelle RuleId, RegexKey et DefaultRegex qui est l'expression Regex par défaut associée à cette règle.

Les paramètres RecommendationMessage et ErrorLevel sont les mêmes que pour la règle présentée précédemment.

Créer des compteurs

Les compteurs représentent les vérifications effectuées pour indiquer le nombre de fois qu'un événement ou une condition spécifique s'est produit.

Leur structure est un peu différente de celle des règles, au sens où le seul paramètre ErrorLevel disponible pour les compteurs est Info. Par conséquent, l'expression permettant de définir le niveau d'erreur pour un compteur doit ressembler à ceci : ErrorLevel = System.Diagnostics.TraceLevel.Info.

Prenons les Statistiques des activités du fichier (File Activities Stats) en exemple pour illustrer l'apparence des règles de compteur en arrière-plan :

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

Construire des règles pour StudioX

Par défaut, les règles ne s’appliquent qu’au profil Studio. Pour faire apparaître une règle dans le profil StudioX également, ajoutez la propriété ApplicableScopes et configurez-la pour qu'elle inclue BusinessRule. Par exemple, vous pouvez ajouter la propriété comme ceci :

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

Enregistrement des règles

Méthode d'interface d'enregistrement

N'oubliez pas qu'en utilisant cette méthode, votre paquet est compatible uniquement avec les versions de Studio 2019.10 ou ultérieures.

Implémentez l'interface IRegisterAnalyzerConfiguration à l'aide de la méthode Initialize(IAnalyzerConfigurationService workflowAnalyzerConfigService)suivante.

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

Remarque : appelez la méthode HasFeature sur le IAnalyzerConfigurationService pour enregistrer les règles d'une version de Studio spécifique.

Méthode IRegisterMetadata

Notez que cette méthode n'est disponible que pour les versions de Studio supérieures à 2019.6 et qu'elle n'est pas aussi appropriée que la méthode d'interface d'enregistrement.

• Ajoutez une annulation de la méthode Initialize(object api) à votre implémentation de IRegisterMetadata.
• Dans votre implémentation de Initialize, transmettez le paramètre object à WorkflowDesignApi, puis ajoutez tous les éléments sous une activité Try Catch juste pour vous assurer que les exceptions sont gérées.
• Une fois que vous avez résolu le WorkflowDesignApi, le WorkflowAnalyzerConfigService est disponible en tant que propriété.
• À ce stade, vous avez accès à la valeur IAnalyzerConfigurationService décrite en détail dans la section ci-dessus.

Ajouter des règles à Studio

Les règles personnalisées de l’analyseur de workflow peuvent être intégrées à Studio de deux manières :

• au niveau global en ajoutant l'assembly externe (.dll) à l'emplacement d'installation de Studio
• au niveau du projet en installant le pack d'activités personnalisé.

Au niveau global

Pour rendre les règles personnalisées disponibles dans tous les projets créés dans votre instance de Studio, vous devez ajouter les packages d’assemblage externe (.dll) à un dossier spécifique depuis lequel Studio charge les règles personnalisées. Par défaut, le chemin de dossier est :

• Dans les versions Studio antérieures à 2021.10 :

  • For per-machine installations: %ProgramFiles%\UiPath\Studio\Rules
  • Pour les installations par utilisateur : %LocalAppData%\Programs\UiPath\Studio\Rules

• Dans Studio 2021.10.6 et versions ultérieures :

  • Pour les installations par machine : %ProgramFiles%\UiPath\Studio\Rules\net6.0 (pour les règles ciblant les projets Windows et multiplate-forme) et %ProgramFiles%\UiPath\Studio\net461\Rules (pour les règles ciblant les projets hérités depuis Windows)
  • Pour les installations par l'utilisateur : %LocalAppData%\Programs\UiPath\Studio\Rules\net6.0 (pour les règles ciblant les projets Windows et multiplate-forme) et %LocalAppData%\Programs\UiPath\Studio\net461\Rules (pour les règles ciblant les projets hérités depuis Windows)

En option, vous pouvez changer le dossier depuis lequel Studio charge les règles personnalisées en accédant à Accueil (Home) (mode Backstage de Studio) > Paramètres (Settings) > Emplacements (Locations) et en définissant d’un Emplacement des règles de l’analyseur de flux de travail personnalisé ( Custom Workflow Analyzer rules location). Cette fonctionnalité est disponible dans Studio v2020.10. ou versions ultérieures.

Suivez les étapes décrites en détail à la page Création d'une activité personnalisée pour exporter le code en tant que fichier .dll.

Au niveau du projet

Pour rendre les règles personnalisées disponibles uniquement pour un certain projet, créez un paquet NuGet (.nupkg) et installez-le dans un projet Studio en tant que dépendance.