通过

安装并配置使用 iOS 进行构建的工具

  • 项目

可以将 Visual Studio 与使用 C++ 进行跨平台移动开发的工具一起使用，以编辑、调试 iOS 代码，并将其部署到 iOS 模拟器或 iOS 设备。 但由于许可限制，必须在 Mac 上远程生成和运行代码。 若要使用 Visual Studio 生成和运行 iOS 应用，需要在 Mac 上安装并配置远程代理 vcremote。 该 vcremote 远程代理会处理来自 Visual Studio 的生成请求，并在连接到 Mac 的 iOS 设备上或 Mac 上的 iOS 仿真程序中运行应用。

注意

有关使用云托管的 Mac 服务而不是 Mac 的信息，请参阅配置 Visual Studio 以连接到云托管的 Mac。 此说明适用于使用 Visual Studio Tools for Apache Cordova 进行生成。 要通过 C++ 使用指令进行生成，请将 vcremote 替换为 remotebuild。

安装完要使用 iOS 生成内容的工具后，请再次参阅本文。 其中介绍了在 Visual Studio 中和 Mac 上快速配置和更新用于 iOS 开发的 vcremote 的方法。

先决条件

若要安装和使用 vcremote 远程代理以开发 iOS 代码，必须首先具备以下先决条件：

  • 运行 macOS Mojave 10.14 版或更高版本的 Mac 计算机

  • Apple ID

  • 有效的 Apple 开发人员计划帐户

    可以获得一个允许将应用旁加载到 iOS 设备的免费帐户，该帐户仅用于测试，不适用于分发。

  • Xcode 10.2.1 版或更高版本

    可从 App Store 下载 Xcode。

  • Xcode 命令行工具

    若要安装 Xcode 命令行工具，请打开 Mac 上的 Terminal 应用并输入以下命令：

    xcode-select --install

  • 在 Xcode 中配置的 Apple ID 帐户作为用于对应用进行签名的签名标识

    若要查看或设置 Xcode 中的签名标识，打开 Xcode 菜单并选择 “首选项”。 选择“帐户” 并选择你的 Apple ID，然后选择“查看详细信息” 按钮。 有关详细说明，请参阅 Add your Apple ID account（添加 Apple ID 帐户）。

    有关签名要求的详细信息，请参阅 What is app signing（什么是应用签名）。

  • 如果使用 iOS 设备进行开发，Xcode 中已为你的设备配置了预配配置文件

    Xcode 提供自动签名，并根据需要创建签名证书。 有关 Xcode 自动签名的详细信息，请参阅 automatic signing（自动签名）。

    如果要进行手动签名，则需要为应用创建预配配置文件。 有关创建预配配置文件的详细信息，请参阅创建开发预置描述文件。

  • Node.js 版本 18.12.1 和 npm 版本 8.19.2

    在 Mac 上安装 Node.js 版本 18.12.1。 如果安装 Node.js 包，该包应附带 npm 8.19.2 版。 其他版本的 Node.js 和 npm 可能不支持 vcremote 中使用的一些模块，这可能导致 vcremote 安装失败。 建议使用包管理器（如 Node 版本管理器）安装 Node.js。 请避免使用命令 sudo 来安装 Node.js，因为使用 sudo 时，某些模块可能安装失败。

安装适用于 iOS 的 vcremote

当使用 C++ 工作负载安装移动开发时，Visual Studio 可以与 vcremote 进行通信，这是一个在 Mac 上运行的远程代理，用于传输文件、生成和运行 iOS 应用，以及发送调试命令。

安装 vcremote 之前，请确保已经满足先决条件并完成了使用 C++ 安装跨平台移动开发中的安装步骤。

下载并安装 vcremote

  • 在你的 Mac 上的终端应用中，验证当前使用的 Node.js 版本是否为要求的版本 18.12.1。 若要查找版本，请运行以下命令：

    node -v

    如果版本不正确，则可能需要按照先决条件中的 Node.js 安装说明进行操作。 然后重启 Node.js。

  • 验证正在使用要求的 Node.js 后，运行以下命令以在该 Node.js 版本下安装 vcremote：

    npm install -g --unsafe-perm vcremote

    全局安装 (-g) 开关是推荐使用而不是必须使用的。 如果不使用全局安装开关，则会在终端应用中的当前活动路径下安装 vcremote。

    在安装期间，vcremote 将被安装在你的 Mac 上，同时将激活开发人员模式。 还会安装 Homebrew 和两个 npm 包，vcremote-lib 和 vcremote-utils。 安装完成后，可以忽略有关跳过可选依赖项的警告。

    注意

    若要安装 Homebrew，你必须具有 sudo（管理员）访问权限。 如果不想以 sudo 份安装 vcremote，可以在 usr/local 位置手动安装 Homebrew 并将其 bin 文件夹添加到你的路径。 有关详细信息，请参阅 Homebrew 文档。 若要手动启用开发人员模式，请在 Terminal 应用中输入以下命令： DevToolsSecurity -enable

如果更新到新版本的 Visual Studio，那么必须将 vcremote 也更新到最新版本。 若要更新 vcremote，请重复下载并安装远程代理的步骤。

启动 vcremote

必须运行 vcremote 远程代理才能通过 Visual Studio 生成并运行 iOS 代码。 Visual Studio 需要与 vcremote 结合使用才能进行通信。 默认情况下，vcremote 在安全的连接模式下运行，这需要在 Visual Studio 和 Mac 计算机之间传输客户端和服务器证书。

注意

1.0.19 或更高版本的 vcremote 需要至少搭配 Visual Studio 2022 版本 17.5.0 预览版 1 或更高版本。 如果使用 Visual Studio 2022 版本 17.4 或更低版本，请安装 vcremote 版本 1.0.17。

启动 vcremote

  • 在 Mac 上的 Terminal 应用中，输入：

    vcremote

    此命令将启动默认生成目录为 ~/vcremote 的远程代理。 有关更多配置选项，请参阅在 Mac 上配置 vcremote。

首次启动 vcremote 及每次创建新服务器证书时，都会提供所需信息来配置 Visual Studio 中的连接。 这些信息包括主机名和端口。 如果打算在 Visual Studio 中使用主机名配置远程代理，请使用该主机名从 Windows 对 Mac 进行 ping 操作，以确认它是可连接的。 否则，你可能需要使用 IP 地址。

你可以在非安全模式下使用远程代理。 在非安全模式下，可以使用不加密数据的简单 HTTP 连接将远程代理配对到 Visual Studio。 使用不安全模式时需自担风险。 建议使用安全模式连接：

Visual Studio 2022 版本 17.5 及更高版本与 vcremote 1.0.19 及更高版本：

在 vcremote 1.0.19 及更高版本中，vcremote 会报告 server-cert.pem 证书文件的路径，需要将该文件上传到 Visual Studio。

Visual Studio 2022 版本 17.4 及更低版本与 vcremote 1.0.17 及更低版本：

1.0.17 及更早版本的 vcremote 会生成 PIN，用于与 Visual Studio 2022 版本 17.4 及之前版本的 Visual Studio 进行安全通信。

Mac 终端窗口的屏幕截图，其中显示了启动 VC 远程时报告的主机名、端口和 PIN。

生成的 PIN 是一次性的，并仅在有限时间内有效。 如果在此有限时间段内未将 Visual Studio 与远程代理进行配对，则需要生成一个新的 PIN。 有关详细信息，请参阅 Generate a new security PIN。

禁用安全连接模式

  • 若要禁用 vcremote 中的安全连接模式，请在 Mac 上的 Terminal 应用中输入以下命令：

    vcremote --secure false

启用安全连接模式

  • 若要启用安全连接模式，请输入此命令：

    vcremote --secure true

启动远程代理后，即可从 Visual Studio 使用该代理，直到你停用它。

停用远程代理

  • 在正在运行 vcremote 的终端窗口中，输入 Control+C。

在 Visual Studio 中配置 vcremote

若要从 Visual Studio 连接到 vcremote 远程代理，必须在 Visual Studio 选项中指定远程配置。 你每次在 Visual Studio 时，它会使用相同信息连接到 Mac 上的远程代理。 除非在 Mac 上生成了新的安全证书，或其主机名或 IP 地址发生了更改，否则，你无需再次将 Visual Studio 与远程代理进行配对。

从 Visual Studio 2022 版本 17.5 及更高版本中配置 vcremote

  1. 如果代理尚未在 Mac 上运行，请按照启动远程代理中的步骤操作。 你的 Mac 必须正在运行 vcremote，Visual Studio 才能顺利配对、连接和生成项目。

  2. 在你的 Mac 上，获取 Mac 的主机名或 IP 地址。

    可以通过在终端窗口中使用 ifconfig 命令来获取 IP 地址。 请使用活动网络接口下列出的 inet 地址。

  3. 在 Visual Studio 菜单栏上，选择“工具”>“选项”。

  4. 在“选项”对话框中，展开“跨平台”>“C++”>“iOS”。

  5. 在“主机名” 和“端口” 字段，输入远程代理在启动时指定的值。 主机名可以是 DNS 名或 Mac 的 IP 地址。 默认端口为 3030。

    注意

    如果无法使用主机名 ping Mac，则可能需要使用 IP 地址。

  6. 如果在默认安全连接模式下使用远程代理，请勾选“安全”复选框，并将 server-cert.pem 文件从 Mac 传输到 Visual Studio 以供上传。 接下来，选择“生成”按钮以生成应会显示在桌面上的新 client-cert.pem 文件。 然后，将客户端证书传输到 Mac 的 /vcremote/certs/Authorized-Clients 下。 （可以将多个客户端证书文件传输到此目录，以便多个经过授权的 Visual Studio 计算机可以将请求发送到此 Mac。）

    注意

    如果使用 USB 驱动器传输证书，请在传输完成后从 USB 驱动器中删除证书。

  7. 选择“配对”以启用配对。

    iOS 配对的“工具选项”对话框的屏幕截图。将设置主机名、端口、安全复选框和远程根值。

    在更改主机名、端口或生成新的服务器或客户端证书之前，相应的配对会一直保留。 如果在“选项”对话框中更改了主机名或端口，可选择“还原”按钮来撤销此更改并还原到上一配对。

    如果配对失败，请按照 Start the remote agent中的步骤验证远程代理是否正在运行。 按照生成新服务器证书和生成新客户端证书中的步骤操作。 如果使用的是 Mac 的主机名，请转而尝试在“主机名” 字段中使用 IP 地址。

  8. 更新“远程根目录”字段中的文件夹名称，以在 Mac 上的主 (~) 目录中指定远程代理所用的文件夹。 默认情况下，远程代理会使用 /Users/<username>/vcremote 作为远程根目录。

  9. 选择“确定” 以保存远程配对连接设置。

从 Visual Studio 2022 版本 17.5 之前的版本中配置 vcremote

  1. 如果代理尚未在 Mac 上运行，请按照启动远程代理中的步骤操作。 你的 Mac 必须正在运行 vcremote，Visual Studio 才能顺利配对、连接和生成项目。

  2. 在你的 Mac 上，获取 Mac 的主机名或 IP 地址。

    可以通过在终端窗口中使用 ifconfig 命令来获取 IP 地址。 请使用活动网络接口下列出的 inet 地址。

  3. 在 Visual Studio 菜单栏上，选择“工具”>“选项”。

  4. 在“选项”对话框中，展开“跨平台”>“C++”>“iOS”。

  5. 在“主机名” 和“端口” 字段，输入远程代理在启动时指定的值。 主机名可以是 DNS 名或 Mac 的 IP 地址。 默认端口为 3030。

    注意

    如果无法使用主机名 ping Mac，则可能需要使用 IP 地址。

  6. 如果以默认安全连接模式使用远程代理，请勾选“安全” 复选框，然后在 Pin 字段输入由远程代理指定的 PIN 值。 如果以非安全连接模式使用远程代理，请清除“安全” 复选框并将 Pin 字段留空。

  7. 选择“配对”以启用配对。

    iOS 配对的“工具选项”对话框的屏幕截图。将设置主机名、端口、安全复选框、pin 和远程根值。

    除非更改主机名或端口，否则配对会一直存在。 如果在“选项” 对话框中更改了主机名或端口，要撤销此更改，请选择“还原” 按钮以还原到上一配对。

    如果配对失败，请按照 Start the remote agent中的步骤验证远程代理是否正在运行。 如果生成远程代理 PIN 后已经过了很久，请执行生成新的安全 PIN 中的步骤。 然后重试。 如果使用的是 Mac 的主机名，请转而尝试在“主机名” 字段中使用 IP 地址。

  8. 更新“远程根目录”字段中的文件夹名称，以在 Mac 上的主 (~) 目录中指定远程代理所用的文件夹。 默认情况下，远程代理会使用 /Users/<username>/vcremote 作为远程根目录。

  9. 选择“确定” 以保存远程配对连接设置。

Generate a new security PIN

适用于：Visual Studio 2022 版本 17.4 及更低版本，使用 vcremote 版本 1.0.17 及更低版本。

当你第一次启动远程代理时，生成的 PIN 在有限的时间（默认 10 分钟）内有效。 如果在此有限时间段内未将 Visual Studio 与远程代理进行配对，则需要生成一个新的 PIN。

生成新的 PIN

  1. 停止代理，或在你的 Mac 上打开另一个 Terminal 应用窗口并使用它输入命令。

  2. 在 Terminal 应用中输入此命令：

    vcremote generateClientCert

    远程代理将生成一个新的临时 PIN。 若要使用新的 PIN 配对 Visual Studio，请重复 在 Visual Studio 中配置远程代理中的步骤。

生成新客户端证书

适用于：Visual Studio 2022 版本 17.5 及更高版本，使用 vcremote 版本 1.0.19 及更高版本。

在 Visual Studio 上配对时，会生成一个新 client-cert.pem 文件。 将证书文件传输到 Mac 生成计算机的 /vcremote/certs/Authorized-Clients 下。 此证书使 Mac 能够向来自 Visual Studio 计算机的请求进行授权。

生成新的服务器证书

适用于：Visual Studio 2022 版本 17.5 及更高版本，使用 vcremote 版本 1.0.19 及更高版本。

出于安全目的，将 Visual Studio 与远程代理配对的服务器证书关联到你的 Mac 的 IP 地址或主机名。 如果这些值已更改，则必须生成一个新的服务器证书，然后使用新值重新配置 Visual Studio。

生成新的服务器证书

  1. 停止 vcremote 代理。

  2. 在 Terminal 应用中输入此命令：

    vcremote resetServerCert

  3. 当提示进行确认时，请输入 Y。

  4. 要将 Visual Studio 与 Mac 配对，请从 Mac 传输新生成的 server-cert.pem 文件并将其上传到 Visual Studio，并重复在 Visual Studio 中配置远程代理的步骤。

在 Mac 上配置 vcremote

你可以使用各种命令行选项配置远程代理。 例如，你可以指定用于接收版本请求的端口以及要在文件系统上进行维护的最大生成数量。 默认限制为 10 个生成。 远程代理会在关机时删除超过最大数量的生成。

配置远程代理

  • 若要查看远程代理命令的完整列表，请在 Terminal 应用中输入：

    vcremote --help

  • 若要禁用安全模式并启用简单的基于 HTTP 的连接，请输入：

    vcremote --secure false

    使用此选项时，请清除“安全”复选框。

  • 要为远程代理文件指定位置，请输入：

    vcremote --serverDir directory_path

    将 directory_path 替换为 Mac 上放置日志文件、生成项和服务器证书的位置。 默认情况下，此位置是 /Users/<username>/vcremote。 生成项会在此位置按照生成号进行整理。

  • 若要使用后台进程以将 stdout 和 stderr 捕获至名为 server.log 的文件，请输入：

    vcremote > server.log 2>&1 &

    server.log 文件可帮助排查生成问题。

  • 若要通过使用配置文件而不是命令行参数来运行代理，请输入：

    vcremote --config config_file_path

    将 config_file_path 替换为 JSON 格式配置文件的路径。 启动选项及其值不得包含短划线。

对远程代理进行故障排除

在设备 iOS 上进行调试

如果在 iOS 设备上进行调试不起作用，则用于与 iOS 设备通信的工具 ideviceinstaller 可能存在故障。 此工具通常在安装 vcremote 时从 Homebrew 安装。 作为临时解决方法，请执行后续步骤：

打开终端应用并按顺序运行以下命令来更新 ideviceinstaller 及其依赖项：

  1. 确保 Homebrew 已更新

    brew update

  2. 卸载 libimobiledevice 和 usbmuxd

    brew uninstall --ignore-dependencies libimobiledevice

    brew uninstall --ignore-dependencies usbmuxd

  3. 安装最新版本的 libimobiledevice 和 usbmuxd

    brew install --HEAD usbmuxd

    brew unlink usbmuxd

    brew link usbmuxd

    brew install --HEAD libimobiledevice

  4. 卸载和重新安装 ideviceinstaller

    brew uninstall ideviceinstaller

    brew install ideviceinstaller

尝试列出设备上安装的应用，以验证 ideviceinstaller 是否可以与设备通信：

ideviceinstaller -l

如果 ideviceinstaller 报告了一个错误，指示其无法访问文件夹 /var/db/lockdown，请使用以下命令更改文件夹的权限：

sudo chmod 777 /var/db/lockdown

然后，再次验证 ideviceinstaller 是否可以与设备通信。

另请参阅