Java 版扩展程序

支持的版本

Java 扩展程序与从 Java 3 到 Java 24 的所有 JRE 版本都兼容。

当尝试在 Java 应用程序中指示或验证选取器时，Robot 会检查目标应用程序进程中是否已加载扩展文件。

这些文件可能通过各种机制存在于其中：

• 通过扩展机制在 JRE（适用于 Java 3 到 8）中安装扩展程序。
• 从自定义文件夹中加载（对于 Java 3 到 17，在 Java 9 之后要遵循不同的步骤）。

如果扩展程序文件不存在，则使用注入机制来尝试启动我们得网桥。

备注：

The Java Extension installer embedded in Studio (and also the ScreenScrapeJavaSupport tool) relies on the extension mechanism to have the extension loaded by the JRE, so it can be used for automating Java-based applications running with Java 3 to 8.

从 Java 9 开始，我们已弃用扩展机制，安装程序无法将必要的文件添加到 JRE。必须从自定义文件夹中加载这些文件（点击此处了解更多信息）。

Starting with UIAutomation package version 22.2.0-preview, with the support of the default injection mechanism, it is no longer mandatory to install the Extension for Java for automating Java-based applications.

You should install the Java extension from Studio or the command line only when the injection mechanism does not work, and when Java applications are using Java 3 to 8. For Java applications using Java 9 or greater, follow the steps described in Installing the extension in a custom folder.

注入机制

在 UiPath.UIAutomation.Activities 版本 22.2.0 预览版之前，注入机制并非在所有情况下都有效。作为主要方法，从自定义文件夹加载扩展程序可用于使用 Java 9+ 启动的应用程序。

从 UiPath.UIAutomation.Activities 22.2.0 预览版开始，注入机制变得更加可靠，并且能够自动化以前无法自动化的应用程序，例如通过 OWS 或 IcedTea Web 等第三方应用程序启动的 .jnlp 应用程序。

默认情况下使用注入机制，并且 Java 扩展程序安装只能用作备用方法。

通过 Studio 或命令行在 JRE 中安装扩展程序

对于 Java 8 或更低版本

您可执行以下操作安装 UiPath Java 扩展程序：

来自 Studio

1. 关闭任何正在运行的 Java 应用程序。
2. 打开 Studio。
3. 导航至“工具”>“UiPath 扩展程序”。
4. 选择“Java”>“安装”。系统将显示一条确认消息，通知您已安装扩展程序。

使用命令行

在命令行提示符窗口中，使用管理员权限运行 C:\Program Files\UiPath\Studio\UiPath\SetupExtensions.exe /Java 命令。

当您尝试在 Java 应用程序中选择控件且未检测到网桥时，Studio 和用户界面探测器也会要求您安装 UiPath Java 扩展程序。如果您听从用户界面探测器的提示而选择安装 UiPath Java 扩展程序，Java 网桥文件将只会部署在启动目标 Java 应用程序的 JRE 目录，而非 JDK 目录中。

注意：要安装此扩展程序，您必须具有管理员权限。

要检查扩展程序是否正常工作，请打开用户界面探测器并尝试在 Java 应用程序中选择控件。如果选择了整个窗口，这意味着扩展程序不能正常工作。

您可以通过为 Java 控件生成的选取器来判断是否已正确安装扩展程序：

• Java 控件的有效选取器：<wnd app=”...” /><java role=”...” />
• Java 控件的无效选取器：<wnd app=”...” /><ctrl role=”client” />

注意：UiPath Java 扩展程序只能兼容 AWT 应用程序（例如 Java Swing、Oracle Forms、Fujitsu JBK），而 SWT 应用程序则是通过主动式辅助实现自动化。要检测 Java 应用程序的类型，请检查用户界面探测器中的 cls 属性（窗口类名）。类名应该类似于 SunAwtFrame 或 javax.swing。

流程可以与 Java 应用程序交互，无论其 DPI 缩放如何。

您还可使用 ScreenScrapeJavaSupport 工具安装 UiPath Java 扩展程序。

对于 Java 9 或更高版本

在自定义文件夹中使用安装程序，如下一节中所述。

在自定义文件夹中安装扩展程序

对于 Java 8 或更低版本

如要在自定义位置安装适用于 Java 的 UiPath 扩展程序，请执行以下步骤：

1. 在要安装适用于 Java 的 UiPath 扩展程序的计算机上创建一个新文件夹（如 C:\UiPathJavaExt），然后将以下文件复制到该文件夹：
   1. UiPathBridge.jar - 位于 %UserProfile%\.nuget\packages\uipath\20.xx.xxxx\build\UiPath\JavaSupport 目录中。
   2. UiPathJavaBridgeV8.dll 和 UiPathJavaBridgeV8_x64.dll - 位于 %UserProfile%\.nuget\packages\uipath\20.xx.xxxx\build\UiPath 目录中。不一定要复制这两个文件，但这可以防止由于 JRE 和 UiPathJavaBridge 之间版本不匹配所引致的问题。
2. UiPath 用于安装扩展程序的 Java 扩展程序设置机制在 Java 安装目录（通常为 C:\Program Files (x86)\Java\jre1.8.0_xx）中部署 UiPathBridge.jar 和 accessibility.properties 文件。若要从自定义文件夹中使用适用于 Java 的 UiPath 扩展程序，则须减少对这些文件的依赖，如下所示：
   1. 对于 UiPathBridge.jar 文件，在启动使用扩展程序的 Java 应用程序时，需要指定复制 UiPathBridge.jar 和 UiPathJavaBridgev8.dll 的文件夹（如 C:\UiPathJavaExt）。这是通过 -Djava.ext.dirs = C:\UiPathJavaExt 参数完成的。
   2. 对于 accessibility.properties 文件，有两种方法：
      • 将 assistive_technologies=UiPath.UiPathBridge 参数添加到位于 %userprofile% 目录的全局配置文件 accessibility.properties 中。请注意，此文件与适用于 Java 的 UiPath 扩展程序所部署的文件不同，其设置优先于 Java 安装所设的设置。
      • 运行目标 java 应用程序时，请使用 -Djavax.accessibility.assistive_technologies=UiPath.UiPathBridge 参数。

系统属性需要正确传递到目标 Java 应用程序。这可以通过几种方法完成：

• 在 _JAVA_OPTIONS 环境变量中包括 -Djava.ext.dirs=C:\UiPathJavaExt -Djavax.accessibility.assistive_technologies=UiPath.UiPathBridge 系统属性。JRE 加载来自环境变量的属性和目标应用程序中加载的 Java 的 UiPath 扩展程序。
• 在命令提示符中使用 C:\Program Files (x86)\Java\jre1.8.0_xx\bin\java.exe -Djavax.ext.dirs=C:\UiPathJavaExt -Djavax.accessibility.assistive_technologies=UiPath.UiPathBridge -jar SwingSet2.jar 命令。将显示一条确认消息，指出适用于 Java 的 UiPath 扩展程序已成功加载。
• 在 JAVA_TOOL_OPTIONS 环境变量中包括 -Djava.ext.dirs=C:\UiPathJavaExt -Djavax.accessibility.assistive_technologies=UiPath.UiPathBridge 系统属性。请注意，此方法仅适用于 Java 5 或更高版本。

使用以下方法之一可将属性传递到 Java 小程序：

1. 使用 appletviewer.exe 应用程序。
   此方法要求您首先在 %userprofile% 文件夹中创建 .java.policy ，并且应包含以下内容：

   grant { 
       permission java.net.URLPermission "url_of_the_Java_applet", "<em>:</em>"; 
   };

   完成操作后，需要使用以下命令并通过 appletviewer.exe 启动目标小程序：

   C:\Program Files (x86)\Java\jre1.8.0_xx\bin\appletviewer.exe -J-Djava.ext.dirs=C:\UiPathJavaExt -J-Djavax.accessibility.assistive_technologies=UiPath.UiPathBridge url_of_the_java_applet

2. 使用与 JRE 一起交付的 Java 控制面板。

   Java 控制面板允许您为每个注册的 JRE 指定运行时参数。因此，您需要指定

   -Djava.ext.dirs=C:\UiPathJavaExt -Djavax.accessibility.assistive_technologies=UiPath.UiPathBridge

   目标小程序的参数。每次 Java 小程序启动时，都会加载 UiPath Java 扩展程序。

下表显示了上述方法、Java 版本和不同类型的 Java 应用程序之间的兼容性：

应用程序类型	_JAVA_OPTIONS	JAVA_TOOL_OPTIONS	命令行参数	Java 控制面板 - 运行时参数
Java 桌面应用程序	Java 3 到 Java 8	Java 5 到 Java 8	Java 3 到 Java 8	不支持
Java 自含的应用程序 (.exe)	Java 3 到 Java 8	Java 5 到 Java 8	Java 3 到 Java 8 (1)	不支持
Java 小程序	Java 3 到 Java 8	Java 5 到 Java 8	不支持	Java 3 到 Java 8
Java Oracle Forms	不支持	不支持	不支持	不支持

(1) - 根据使用的命令行工具，可能需要通过环境变量传递其他参数。

对于 Java 9 或更高版本

从 Java 9 开始，将删除 Java 扩展机制，这意味着 -Djava.ext.dirs 参数不能用于 Java 9 和更高版本的应用程序。

加载扩展程序主要出于以下 3 个要求：

1. 将 UiPathBridge.jar 和 UiPathServiceProvider.jar 添加到应用程序的类路径中。
2. 使 UiPathJavaBridgeV8.dll 和 UiPathJavaBridgeV8_x64 对 UiPathBrdige.jar 可见。这可以通过多种方式完成：
   • 使用 UiPathBridge.jar 将文件放置在同一文件夹中；
   • 将文件放置在 UiPathBridge.jar 上方的文件夹中；
   • 将这两个文件添加到文件夹中，并通过名为 UIPATH_JB_PATH 的环境变量引用其路径；

     不一定要引用这两个文件，但这可以防止由于 JRE 和 UiPathJavaBridge 之间版本不匹配所引致的问题。

3. 配置应用程序以加载辅助技术。这是通过放置在 JRE 中的 accessibility.properties 文件完成的。
   注意：UiPathJavaServiceProvider.jar 文件位于最新的 UiPath.UIAutomation.Activities 包（21.2 预览版以上版本）中。如果您使用的是较低版本的 UIAutomation，则可以通过将空的工作流文件临时升级到 21.2 预览版来获取文件。这将导致 UiPath.nuget 包的较新版本解压缩到用户计算机 (%UserProfile%\.nuget\packages\uipath)。获取文件后，可以将包降级为升级前使用的版本。

是否满足上述要求直接取决于 Java 应用程序的启动方式。启动应用程序和加载扩展程序的常见方式有 3 种。

从 .jar、.bat 或 .ps1 文件启动的应用程序

我们来考虑一个简单的情况，即直接从简单的 .jar 文件启动应用程序：java -jar SwingSet2.jar

需要执行以下步骤：

1. 在要安装适用于 Java 的 UiPath 扩展程序的计算机上创建一个新文件夹（如 C:\UiPathJavaExt），然后将以下文件复制到该文件夹：
   • UiPathBridge.jar 和 UiPathJavaServiceProvider.jar - 位于 %UserProfile%\.nuget\packages\uipath\20.xx.xxxx\build\UiPath\JavaSupport 目录中。
   • UiPathJavaBridgeV8.dll 和 UiPathJavaBridgeV8_x64.dll - 位于 %UserProfile%\.nuget\packages\uipath\20.xx.xxxx\build\UiPath 目录中。
2. 将以前创建的文件夹添加到目标 Java 应用程序的类路径。此操作使用 -cp, -classpath 命令完成。对于此示例，我们将 SwingSet2 视为目标 Java 应用程序：

   C:\Program Files (x86)\Java\jre1.9.0_xx \bin\java.exe -cp SwingSet2.jar;C:\UiPathJavaExt\* -Djavax.accessibility.assistive_technologies=UiPathJavaServiceProvider SwingSet2

如果应用程序通过 .bat 或 .ps1 文件启动，则必须使用文本编辑器分析该文件。启动应用程序的文件包含与命令 java -jar SwingSet2.jar 类似的行，但还包含许多其他参数。可以更改命令以将文件包含在类路径中，并指定辅助技术参数。更改这些文件时应格外小心。在某些情况下，从环境变量中选取类路径和其他参数，这是一种侵入性较小的方法。

从 .exe 文件启动的应用程序

当通过 .exe 文件启动应用程序时，则必须找到一种将文件加载到类路径并指定辅助技术参数的替代方法。

1. 要从类路径加载文件，您可以搜索可执行程序读取的环境变量或指定依赖项加载位置的配置文件。这里没有标准，这在很大程度上取决于可执行文件的自定义级别。
2. 在这种情况下，可以通过与扩展程序安装程序类似的方式指定辅助技术。可将标准 accessibility.properties 文件移动到 %UserProfile% 文件夹，并将其重命名为 .accessbility.properties。

从 .jnlp 文件启动的应用程序

从 UiAutomation v22.2 开始，由于现有注入机制升级，默认情况下会与 .jnlp 类型的应用程序交互。

应用程序扩展支持

通过参数，Java 9 以上版本的应用程序完全支持缩放。考虑将以下参数添加到要自动启用扩展支持的 Java 应用程序中：

• sun.java2d.uiScale.enabled - 未使用或设置为精确的字符串值“true”时，将其视为 true，并考虑以下缩放配置。当设置为除“true”以外的任何其他值（例如 True、false、False、abc）时，则将其视为 false，并且不进行其他缩放比例调整。
• sun.java2d.uiScale - 值可以 3 种形式传递：
  • 比率（0.5、2.3、1.5）
  • 百分比（100％、150％）
  • DPI 值（96dpi、120dpi）。考虑是否启用缩放。它修改两个轴上的缩放比例。
• sun.java2d.win.uiScaleX, sun.java2d.win.uiScaleY 可以像 sun.java2d.uiScale 参数一样传递值。Java 应用程序必须考虑这两个参数。它们比扩展的常规配置更具体。因此，如果设置了所有 3 个参数，则仅考虑这些参数。