关于工作流分析器

工作流分析器是一种静态代码分析器，可确保您的项目符合高质量和可靠性标准。静态代码分析器可在不实际执行项目的情况下检查不一致问题，这与在执行期间介入的动态分析器不同。

工作流分析器使用一组规则检查与项目执行无关的各种不一致问题。这些规则基于自动化最佳实践，并且会考虑变量和参数命名、空序列或工作流以及包限制等。该分析器无法识别执行或编译中的错误。

其位于设计功能区选项卡中，分别是分析文件和分析项目按钮。“分析文件”会对设计器面板中设为当前焦点的文件执行分析，而“分析项目”则对自动化项目中的所有文件执行分析。

Studio 带有一组内置规则，可通过前缀 ST- 识别。UIAutomation.Activities、Excel.Activities、Testing Activities 和 Mail.Activities 也自带通过前缀标识的规则。详情请参阅下表：

规则类别	描述	来源
命名	检查文件或项目中是否存在任何与命名相关的不一致问题。	Studio
设计	确保您的项目符合一系列通用最佳实践。	Studio
项目剖析	确保您的项目符合剖析方面的通用要求。	Studio
可维护性和可读性	确认项目简单易懂，从而确保可维护性。	Studio
用法	确保项目中定义的元素得到实际使用。	Studio
性能和可重用性	检查文件或项目中是否存在任何与性能和可重用性相关的不一致问题。	Studio
可靠性	检查文件或项目中是否存在任何与可靠性相关的不一致问题。	Studio
安全性	检查文件或项目中是否存在任何与安全相关的不一致问题。	Studio
应用程序测试	测试工作流和自动化项目。	活动
用户界面自动化活动	验证使用传统或新式用户界面自动化活动的工作流。	活动
Excel 活动	验证使用 Excel 活动的工作流。	活动
邮件活动	验证使用邮件活动的工作流。	活动

您还可以创建自定义规则。 有关更多信息，请参阅开发者指南中的 构建工作流分析器规则 。

在 Automation Ops 中创建 Studio 策略时，也可以配置规则。有关更多信息，请参阅 Automation Ops 指南。

注意：无法将 Studio 内置规则移植到较旧的 Studio 版本。但是，兼容活动包中的规则可以在工作流分析器随附的较旧 Studio 版本中使用。

规则命名惯例

每个规则都包含 ID、名称、说明和建议。 ID 包含来源、类别和编号。 例如， “变量命名惯例” 的 ID 为 ST-NMG-001 ：

• ST - 表明该规则是 Studio 的内置规则。
• NMG - 表示该规则属于“ 命名规则” 类别的一部分。 属于“ 项目剖析规则” 类别的规则包含 ANA 缩写，属于“ 设计最佳实践 ”类别的规则包含 DBP缩写，依此类推。
• 001 - 规则编号。
  
  

  

  
  

范围

每个规则都有一个适用的作用域：

• 活动：在活动级别强制执行规则，并检查变量、参数、属性。变量命名惯例即属于此类规则。
• 工作流：规则在单个项目文件中执行检查，例如 未使用的变量。
• 项目：在项目级别执行检查。

操作

规则包含许多可设置的操作：

• 错误：在错误列表面板中生成错误。
• 警告：在错误列表面板中生成警告。
• 信息：在错误列表面板中生成消息。
• Verbose：创建大型日志文件。

请查看日志记录级别页面，详细了解 Studio 中的日志记录。

管理规则

按照“项目设置”窗口中的一组规则分析项目或文件：

• 在“项目”面板中，单击 图标，然后选择“工作流分析器”。
• 在功能区中，单击“分析文件”按钮，然后从下拉列表中选择“工作流分析器设置”。

默认情况下，规则按窗口中的代码排列，并先显示已启用的规则。

使用窗口顶部的搜索框，按名称或代码搜索规则。要按作用域和默认操作筛选规则，请单击搜索框右侧的 按钮。

配置规则

您可以使用规则左侧的复选框启用/禁用规则，也可以使用右侧的下拉列表更改默认操作。

某些规则不需要其他配置，而其他规则包含您可以配置的参数，例如不得超过的阈值，或者允许或禁止的特定项目的列表。请注意，当您配置包含文本字段的规则（例如，安全字符串滥用或包限制）时，不应在输入文本时给文本加引号。

重置为默认值

对规则的默认值（正则表达式或阈值）作出任何更改后，可以通过右键单击规则，然后选择“重置为默认值”来将值恢复为默认值。

验证

每当触发工作流分析器时，系统都会对文件或项目执行验证。验证选项位于分析文件功能区按钮中，分别是“验证文件”和“验证项目”。

此操作检查是否已正确配置变量、参数、表达式和导入。可使用 F8 快捷键触发验证文件操作，使用 Shift + F8 触发验证项目操作。可随时取消验证。

系统会在项目面板中以红点标记包含错误的文件，并在错误列表和输出面板中显示错误信息。

双击“错误列表”面板中的项目将打开 .xaml 并突出显示引发错误的元素，无论是活动、参数还是变量。

除非所有 .xaml 文件都经过验证，否则无法调试、执行或发布项目。不评估断点条件。

管理错误

经触发后，工作流分析器会使用配置的规则集检查项目或文件，并根据规则操作在错误列表面板中记录发现的错误。

在“错误列表”面板中，您可以按“错误”、“警告”和“消息”筛选项目。您可以使用“作用域”下拉菜单，按项目、当前文件或自动化中的特定文件筛选错误。此外，还可按规则 ID 筛选项目。

单击发现的警告或错误，以显示规则建议和每个规则的文档页面链接。

除了违反规则外，“错误列表”面板还显示在执行工作流分析时可能发生的错误。当“工作流分析器”或已配置的规则之一无法运行时，将记录错误，并在描述中详细说明错误原因。

命令行支持

UiPath.Studio.CommandLine.exe 命令行用户界面包含一组参数，用于根据特定规则检查文件或项目，即使在 CI/CD 管道配置中也是如此。

UiPath.Studio.CommandLine.exe 位于安装文件夹中：

• 对于基于计算机的安装，默认路径为 %ProgramFiles%\UiPath\Studio\。
• 对于基于用户的安装，默认路径为 %LocalAppData%\Programs\UiPath\Studio。

备注： UiPath.Studio.CommandLine.exe不需要 Studio 许可证。

配置规则

默认情况下，安装 Studio 时会启用所有工作流分析器规则，但以下情况除外：

• 参数默认值
• 未定义的输出属性

您可以配置规则：

• 在“工作流分析器设置”窗口中，通过单击每个规则旁边的复选框来启用或禁用规则。
• 在 RuleConfig.json 文件中，路径 %LocalAppData%\UiPath\Rules。查找特定规则，修改其参数，将 IsEnabled 参数更改为 false 以禁用该规则。（可选）如果路径不可访问，则可以将 RuleConfig.json 文件放入自定义位置，并将该文件的路径包括在命令中。有关详细信息，请参阅分析文件和项目。

系统会按规则的唯一 ID 对其进行整理，并且会在“工作流分析器设置”中显示这些规则。

例如，下图仅启用 变量命名惯例 规则，并接收 ([A-Z]) 正则表达式。 这意味着变量名称必须使用大写字母。 在此示例中，禁用了所有其他规则。

以下参数适用于每个规则：

参数	描述
RuleId	规则的 ID。
IsEnabled	规则是启用还是禁用。如果设置为 null，则应用参数 defaultiseNabled 的值。
DefaultIsEnabled	默认情况下，是启用还是禁用规则。
DefaultErrorLevel	日志消息的默认级别（Error、Warning、Info、Verbose）。
Parameters	规则可以包含的其他参数（例如，名称或值）。
ErrorLevel	日志消息的级别。如果设置为 null，则应用参数 DefaultErrorLevel 的值。

分析文件和项目

配置完规则后，请访问 UiPath.Studio.CommandLine.exe 命令行用户界面。

以下工作流分析器命令可用：

• analyze - 分析整个项目。必须提供 project.json 文件的路径。
• analyze-file - 分析单个文件。必须提供 .xaml 文件的路径。

以下参数可用于工作流分析器命令：

参数	描述
-p, --project-path	分析一个文件时，应提供 .xaml 的路径。分析整个项目时，应指定 project.json 文件的路径。
-c, --config-path	RuleConfig.json 文件的路径。仅当规则配置文件未置于默认位置 (%LocalAppData%\UiPath\Rules) 时，才指定此路径。
--help	查看可用于每个命令的参数。
--version	查看 UiPath.Studio.CommandLine.exe 的版本。

例如，命令 UiPath.Studio.CommandLine.exe analyze-file -p "C:\BlankProcess\Main.xaml" 仅分析项目中的一个文件，即 Main.xaml。该命令的输出返回一个 json 编码的字典，其中包含针对每个违反规则的以下信息：

• FilePath：所分析文件的路径。
• ErrorCode：规则 ID。
• ActivityDisplayName：活动的显示名称（如果不适用，则为 null）。
• Item - 生成错误消息的项目的名称和类型（例如，活动或变量）。
• ErrorSeverity：DefaultAction 参数（为每个规则配置的日志消息）的值，即 Warning、Error、Info 或 Verbose。
• Description：规则的说明。
• Recommendation 和 URL：为解决问题提供的更改建议，以及包含更多信息的文档链接。
  
  

  

  
  

如要使用放置在自定义位置的 RuleConfig.json 文件，请将位置添加到命令中。以上一个命令为例，要使用位于 C:\CustomFolder\RuleConfig.json 的文件配置规则，请运行命令，如下所示：UiPath.Studio.CommandLine.exe analyze-file -c "C:\CustomFolder\RuleConfig.json" -p "C:\BlankProcess\Main.xaml"。

若要返回命令的退出代码，请在运行后执行 echo %errorlevel%。如果没有包含 ErrorSeverity 错误的消息，则将返回 0 代码。否则，将返回 1。

请注意，有些条目可能与规则无关，而是“工作流分析器”生成的错误。例如，在 .xaml 文件为空的情况下，系统会显示错误。

用作条目前缀的全局唯一标识符 (GUID) 在每次运行时生成，并且仅应用于当前结果。

导出工作流分析器结果

要将 Studio 配置为将每次工作流分析的结果导出到项目文件夹，请转到“Studio 后台视图”>“设置”>“设计”，并启用“导出分析器结果”选项。

启用此选项后，每次工作流分析的结果将保存在项目文件夹 \.local\.analysis\ 子文件夹的文件中，该文件命名方式为：分析时间戳后跟 project_analysis_results.json（使用“分析项目”选项时）或 file_analysis_results.json（使用“分析文件”选项时）。

注意：.local 文件夹已隐藏。您可以从“Windows 文件资源管理器”设置中启用隐藏项目查看功能。

文件中包含有关每个已启用规则的下列信息：

• RuleId - 规则 ID。
• RuleName - 规则的名称。
• Parameters - 规则中的可自定义参数（如果适用）。
• Severity - 违反规则时的规则操作。
• ErrorsDescription - 规则生成的错误消息列表（如果适用）。

在运行、发布或推送/签入之前强制执行工作流分析器

通过启用“Studio 后台视图”>“设置”>“设计”中的以下选项，可以防止执行、发布和推送/签入包含工作流分析器错误的远程存储库项目：

• “运行前强制使用分析器” - 每当启动运行/调试文件或项目时，工作流分析器都会使用 Error 操作检查所有规则，并且只有在未发现错误的情况下才允许执行。
• “在发布前强制使用分析器” - 每当发布启动时，工作流分析器都会检查所有启用的规则，无论它们采取何种操作，并且仅当操作 Error 不违反任何规则时才允许发布。
• 在推送/签入之前强制执行分析器 - 每当启动将项目发送到远程存储库时（对于 GIT，提交并推送，对于 SVN 和 TFS，签入），工作流分析器都会检查所有已启用的规则，无论其操作如何，并且仅当操作 Error 没有违反规则时才允许操作。

启用“发布前强制使用分析器”时，如果发布成功（Error 操作没有违反规则），工作流分析结果将包含在文件 project_analysis_results.json（位于 \lib\net45\.analysis\）中已发布的 .nupkg 包中。该文件包含有关每个已启用规则的下列信息：

• RuleId - 规则 ID。
• RuleName - 规则的名称。
• Parameters - 规则中的可自定义参数（如果适用）。
• Severity - 违反规则时的规则操作。
• ErrorsDescription - 规则生成的错误消息列表（如果适用）。