Building Workflow Analyzer Rules

ワークフロー アナライザーはプロジェクトがベスト プラクティス、保守性、わかりやすさ、パフォーマンス、再利用性、信頼性、セキュリティの要件に確実に従うようにするためのツールです。

これらの概念は、大規模なオートメーション プロジェクトを集約することができる、クリーンで信頼性の高いワークフローを確保するために重要です。

メモ： カスタム ルールを作成するには、 オフィシャル フィードの UiPath.Activities.API パッケージが必要です。SDK パッケージは、カスタム プロジェクトの開発依存関係として使用する必要があります。 開発依存関係について詳しくは、こちらをご覧 ください。

以下のビデオで、カスタム ルールの構築方法と、Activity Creator 拡張機能を使用したカスタム アクティビティの作成方法のステップバイステップ の手順を確認 してください。

既製のフォームでは、Workflow Analyzer は Studio に統合され、検証およびアナライザー機能が組み込まれています。検証でエラーが返された場合、分析を実行できません。

Workflow Analyzer の概念

プロジェクトのカスタム ルールを作成するには、Workflow Analyzer が背後でどのように機能するかをよりよく理解するために、いくつかの概念を定義する必要があります。

注:

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

• v2021.4 以前の Studio: .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.

ルールとカウンター

Workflow Analyzer は特定の基準を使用して、プロジェクトの信頼性が満たされていることを確認します。これらのチェックは、慎重に定義されたルールやカウンターを使用して実行されます。

ルールは、満たさなければならない要件を表します。ルール定義に対して検査対象をチェックするように設定できます。

カウンターは、特定のイベントまたは条件が発生した回数を確認するために行われたチェックを表します。

満たされていない各ルールについて、[エラー リスト] パネルに、警告、エラー、情報、または詳細メッセージの形式でメッセージが表示されます。これらのリストには、変更を行い、ルールが満たされていることを確認するための推奨事項も含まれています。

Note: When creating custom rules and counters, we recommend following the naming convention detailed in the About Workflow Analyzer page.

検査対象

Workflow Analyzer は、事前定義されたオブジェクトの詳細な分析を実行できます。オブジェクトは、分析される範囲、ルールまたはカウンターが適用される領域を表します。

• アクティビティ: 検査対象となる最小のオブジェクトです。たとえば、変数の命名規則、変数名が最大文字数を超過、ファイル アクティビティの統計は、アクティビティを検査するために設定可能な、すぐに使える 3 つのルールです。
• ワークフロー: 単一のプロジェクト ファイルでチェックを実行するように、ルールまたはカウンターを設定できます。 [高引数数] と [ 空のシーケンス ] は、スコープとしてワークフローを持つ、2 つの定義済みのルールです。
• プロジェクト: チェックはプロジェクト レベルで実行され、プロジェクトの信頼性が保証されます。 未使用の依存関係 は、プロジェクト スコープに適用されるルールです。

ルールの作成

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.

カスタム ルールを作成するために、ワークフロー アナライザーの変数名が最大文字数を超過で事前定義された最新のルールを見てみましょう。このルールは、プロジェクトで定義されている変数の長さが 20 文字未満であるかどうかをチェックします。このルールの検査対象はアクティビティです。

背後では、ルールは次のようになります。

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

RuleId パラメーターには、ルールの名前を設定する必要があります。この例では、可変長の超過ルールが ST-NMG-008 ルール ID を持ち、ルール命名規則に従います。 Studio の既定のルールで使用されている命名規則の使用は必須ではありません。

RecommendationMessage パラメーターは、分析の完了後に見つかった不整合をユーザーが解決するのに役立つ推奨事項としてメッセージを表示する必要があります。メッセージは簡潔で、明確な手順を示す必要があります。

ErrorLevel パラメーターは、条件が満たされない場合に実行される既定の操作を示します。この例では、ルールは警告をスローします。既定の操作は、エラー、警告、情報、または詳細です。

パラメーターを使用してルールを作成

カスタマイズ可能なパラメーターを含むルールを作成する場合、状況は若干異なります。このようなルールの一つが変数命名規則です。その検査要素はアクティビティであり、変更可能な既定の正規表現を保持しています。

背後では、このルールは次のようになります。

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

このルールに関連付けられた既定の正規表現である RuleId、RegexKey、DefaultRegex を呼び出します。

RecommendationMessage および ErrorLevel パラメーターは、以前に提示されたルールと同じです。

カウンターの作成

カウンターは、特定のイベントまたは条件が発生した回数を確認するために行われたチェックを表します。

それらの構造は、ルールの構造とは少し異なります。カウンターで使用できる唯一の ErrorLevel パラメーターは Info になります。したがって、カウンターのエラーレベルを定義する式はこの ErrorLevel = System.Diagnostics.TraceLevel.Info のようになります。

カウンターのルールがバックエンドでどのように見えるか、ファイル アクティビティの統計を例に取って見ましょう。

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

StudioX のルールの構築

既定では、ルールは Studio のプロファイルにしか適用されません。StudioX のプロファイルにも表示されるようにするには、ApplicableScopes プロパティを追加し、BusinessRule を含めるように設定します。たとえば、次のようなプロパティを追加します。

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

ルール登録

登録インターフェイスメソッド

このメソッドを使用すると、パッケージを Studio バージョン 2019.10 以降でのみ使用できるようになることに留意してください。

次のメソッド Initialize(IAnalyzerConfigurationService workflowAnalyzerConfigService) を使用して IRegisterAnalyzerConfiguration インターフェイスを実装します。

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

メモ： IAnalyzerConfigurationService の HasFeature メソッドを呼び出して、特定のバージョンの Studio のルールを登録します。

IRegisterMetadata メソッド

この方法は、2019.6 以降のバージョンの Studio でのみ使用可能であり、登録インターフェイス メソッドほど適切ではないことに留意してください。

• IRegisterMetadata の実装にメソッド無効 Initialize(object api) を追加します。
• Initialize 実装では、object パラメーターを WorkflowDesignApi にキャストし、例外が管理されることを確認するためだけに [トライ キャッチ] の下にすべてを追加します。
• WorkflowDesignApi を解決すると、WorkflowAnalyzerConfigService をプロパティとして使用できるようになります。
• この時点で、上記のセクションで説明した IAnalyzerConfigurationService にアクセスできます。

Studio にルールを追加

ワークフロー アナライザーのカスタム ルールは、次の 2 つの方法で Studio に統合できます。

• グローバル レベルで、Studio のインストール場所に外部アセンブリ (.dll) を追加
• プロジェクト レベルで、カスタム アクティビティ パッケージをインストール

グローバル レベル

Studio のインスタンスで作成されたすべてのプロジェクトでカスタム ルールを使用できるようにするには、カスタム ルールの読み込み元フォルダーに外部アセンブリ (.dll) パッケージを追加する必要があります。既定では、フォルダー パスは次のとおりです。

• v2021.10 より前のバージョンの Studio では、以下の手順を実行します。

  • For per-machine installations: %ProgramFiles%\UiPath\Studio\Rules
  • ユーザー単位のインストールの場合: %LocalAppData%\Programs\UiPath\Studio\Rules

• v2021.10.6 以降の Studio では、以下の手順を実行します。

  • マシン単位のインストールの場合: %ProgramFiles%\UiPath\Studio\Rules\net6.0 (Windows プロジェクトおよびクロスプラットフォーム プロジェクトをターゲットとするルールの場合) および %ProgramFiles%\UiPath\Studio\net461\Rules (Windows - レガシ プロジェクトをターゲットとするルールの場合)
  • ユーザー単位のインストールの場合: %LocalAppData%\Programs\UiPath\Studio\Rules\net6.0 (Windows プロジェクトおよびクロスプラットフォーム プロジェクトをターゲットとするルールの場合) および %LocalAppData%\Programs\UiPath\Studio\net461\Rules (Windows - レガシ プロジェクトをターゲットとするルールの場合)

Optionally, you can change the folder from which Studio loads custom rules by going to Home (Studio Backstage View) > Settings > Locations and defining a Custom Workflow Analyzer rules location. This feature is available in Studio v2020.10. and later.

「 カスタム アクティビティを作成する 」ページに記載された手順に従って、コードを .dll としてエクスポートします。 ファイル。

プロジェクト レベル

カスタム ルールを特定のプロジェクトのみで利用できるようにするには、NuGet パッケージ (.nupkg) を作成し、依存関係として Studio プロジェクトでインストールします。