sdk

latest

false

重要 :

请注意，此内容已使用机器翻译进行了部分本地化。新发布内容的本地化可能需要 1-2 周的时间才能完成。

开发者指南

上次更新日期 2025年10月30日

构建工作流分析器规则

工作流分析器工具用于确保项目遵循最佳实践，以及可维护性、可读性、性能、可重用性、可靠性和安全性要求。

若要确保获取简洁、可靠的工作流以概述大型自动化项目，这些概念非常重要。

注意：要构建自定义规则，您需要官方订阅源中的 UiPath Activities.Api 包。 SDK 包必须用作自定义项目中的开发依赖项。阅读有关开发依赖项的更多信息。

观看下面的视频，获取有关如何构建自定义规则以及如何使用“ 使用 Activity Creator” 扩展程序创建自定义活动的分步说明。

在其现用形式中，工作流分析器已集成到 Studio 中，并包含验证和分析器功能。如果验证返回错误，则无法完成分析。

工作流分析器概念

要为您的项目构建自定义规则，请定义一系列概念，以便更好地理解工作流分析器的工作原理。

备注：

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

Studio 2021.4 及更早版本：.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.

规则和计数器

工作流分析器利用特定标准来确保满足项目的可靠性要求。它会使用精心定义的规则和计数器执行这些检查。

规则代表必须满足的要求。您可设置规则，以按照规则定义对检查对象执行检查。

计数器表示为确定特定事件或条件的发生次数而进行的检查。

对于每个未满足的规则，“错误列表”面板中将会以 warning、error、info 或 verbose 形式列出相应消息。这些列表中还包含用于确保满足规则的更改建议。

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

检查对象

工作流分析器能对预定义对象执行深度分析。对象代表要进行分析的作用域，亦即强制执行规则或计数器的区域。

活动：它是最小的检查对象。例如， “ 变量命名惯例 ”、“ 变量名称长度超出限制 ” 和“ 文件活动统计信息” 是三个开箱即用的规则，设置后即可用于检查活动。
工作流: 可以将规则或计数器设置为仅在单个项目文件中执行检查。 “参数数量过多” 和“ 空序列 ”是两个以工作流为作用域的预定义规则。
项目：在项目级别执行检查，以确保满足项目的可靠性要求。 “未使用的依赖项 ”是在项目作用域中应用的规则。

创建规则

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 };
            }
        }
    }// 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 参数需要提供规则名称。在此示例中，“ 变量名称长度超出限制 ” 规则的 ID 为 ST-NMG-008 ，并遵循“ 规则命名惯例”。请注意，Studio 中默认可用的规则所使用的命名约定不是强制性的。

RecommendationMessage 参数需要显示一条建议消息，以帮助用户解决完成分析后发现的任何不一致问题。消息内容应简洁明了，并要提供明确步骤。

ErrorLevel 参数声明当未满足条件时将采取的默认操作。在本示例中，此规则引发了警告。默认操作可以是 error、warning、info 或 verbose。

构建包含参数的规则

当我们要构建包含可自定义参数的规则时，情况会略有不同。其中一个规则是 “ 变量命名惯例”。其检查元素是活动，并带有默认的正则表达式（可以更改）。

此规则的工作原理如下：

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 };
            }
        }
    }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) }
            };
        }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 }
            };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 版或更高版本。

使用如下方法实现 IRegisterAnalyzerConfiguration 接口：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());
        }
    }
}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 方法

请注意，此方法仅适用于 Studio 2019.6 以上版本，且与注册接口方法相比较为逊色。

在您的 IRegisterMetadata 实现中添加 void 方法 Initialize(object api)。
在 Initialize 实现中，将 object 参数转换为 WorkflowDesignApi，然后将所有内容添加到“异常处理”活动下，以确保妥善解决任何异常。
解析 WorkflowDesignApi 后，即可获得 WorkflowAnalyzerConfigService 属性。
此时，您可以访问上一部分中详述的 IAnalyzerConfigurationService。

在 Studio 中添加规则

您可通过以下两种方法将自定义工作流分析器规则集成到 Studio 中：

at global level by creating a NuGet package (.nupkg) from the external external assembly (.dll).
项目级别：安装自定义活动包。

全局级别

To make custom rules available in all the projects created in your instance of Studio:

Create a NuGet package (.nupkg) from the external assembly (.dll) packages.
Upload the .nupkg package to a custom feed.
Create a policy in Automation Ops that deploys the feed to Studio and enforces the .nupkg package with the custom rules. To learn more, refer to Manage Sources in the Automation Ops user guide.

Manually adding the assembly (.dll) packages

Important: This method is not recommended, as .dll packages can be blocked by antivirus software.

Alternatively, you can add the external assembly (.dll) packages to a specific folder from which Studio loads custom rules. By default, the folder path is:

在 2021.10 之前的 Studio 版本中：
- For per-machine installations: %ProgramFiles%\UiPath\Studio\Rules
- 对于基于用户的安装： %LocalAppData%\Programs\UiPath\Studio\Rules
在 Studio 2021.10.6 及更高版本中：
- 对于每台计算机安装：%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 文件形式导出代码。