Instalar e configurar ferramentas de build usando o iOS

  • Artigo

Você pode usar o Visual Studio com o desenvolvimento móvel multiplataforma com ferramentas C++ para editar, depurar e implantar código iOS no Simulador do iOS ou em um dispositivo iOS. Mas, devido a restrições de licenciamento, o código deve ser criado e executado remotamente em um Mac. Para compilar e executar aplicativos iOS usando o Visual Studio, é necessário instalar e configurar o agente remoto, vcremote, no Mac. O agente remoto vcremote manipula solicitações de compilação do Visual Studio e executa o aplicativo em um dispositivo iOS conectado ao Mac ou no Simulador iOS no Mac.

Observação

Para saber mais sobre como usar os serviços hospedados em nuvem do Mac, em vez de um Mac, confira Configurar o Visual Studio para se conectar ao seu Mac hospedado na nuvem. As instruções são para compilação usando as Ferramentas do Visual Studio para Apache Cordova. Para usar as instruções para compilar usando C++, substitua vcremote por remotebuild.

Depois de instalar as ferramentas para criar usando o iOS, consulte este artigo novamente. Ele descreve maneiras de configurar e atualizar rapidamente o vcremote para desenvolvimento iOS no Visual Studio e no Mac.

Pré-requisitos

Para instalar e usar o agente remoto vcremote para desenvolver código para iOS, você deve primeiro ter estes pré-requisitos:

  • Um computador Mac executando macOS Mojave versão 10.14 ou posterior

  • Uma Apple ID

  • Uma conta do Programa de Desenvolvedor da Apple ativa

    Você pode obter uma conta gratuita que permita aplicativos de sideload para um dispositivo iOS somente para teste, mas não para distribuição.

  • Xcode versão 10.2.1 ou posterior

    O Xcode pode ser baixado da App Store.

  • Ferramentas de linha de comando Xcode

    Para instalar as ferramentas de linha de comando Xcode, abra o aplicativo Terminal no Mac e digite o seguinte comando:

    xcode-select --install

  • Uma conta de ID da Apple configurada no Xcode como uma identidade de assinatura para assinar aplicativos

    Para ver ou definir a identidade de assinatura no Xcode, abra o menu do Xcode e escolha Preferences (Preferências). Selecione Accounts (Contas) e escolha sua Apple ID e, em seguida, escolha o botão View Details (Exibir Detalhes). Veja Adicionar sua conta de ID da Apple para obter instruções detalhadas.

    Para obter informações detalhadas sobre requisitos de assinatura, consulte O que é a assinatura de aplicativo.

  • Se você estiver usando um dispositivo iOS para desenvolvimento, um perfil de provisionamento configurado no Xcode para seu dispositivo

    O Xcode fornece assinatura automática, onde cria certificados de assinatura para você, conforme necessário. Para obter informações detalhadas sobre a assinatura automática do Xcode, consulte Assinatura automática.

    Se quiser fazer a assinatura manual, você precisará criar um perfil de provisionamento para seu aplicativo. Para obter informações detalhadas sobre como criar Perfis de provisionamento, consulte Criar um perfil de provisionamento de desenvolvimento.

  • Node.js versão 18.12.1 e npm versão 8.19.2

    Instale a versão 18.12.1 do Node.js no Mac. Se você instalar o pacote Node.js, ele deve vir com a versão npm 8.19.2. Outras versões do Node.js e npm podem não suportar alguns módulos usados no vcremote, o que pode causar falha na instalação do vcremote. Recomendamos que você instale Node.js usando um gerenciador de pacotes, como o Node Version Manager. Evite usar o comando para instalar o Node.js sudo , pois alguns módulos podem falhar ao instalar ao usar o sudo.

Instalar vcremote para iOS

Quando você instala a carga de trabalho de desenvolvimento móvel com C++, o Visual Studio pode se comunicar com o agente remoto vcremote em execução no Mac para transferir arquivos, compilar e executar seu aplicativo iOS e enviar comandos de depuração.

Antes de instalar o vcremote, verifique se você atendeu aos pré-requisitos e concluiu as etapas de instalação em Instalar desenvolvimento móvel entre plataformas com C++.

Para baixar e instalar o vcremote

  • No aplicativo Terminal no Mac, verifique se a versão Node.js atualmente em uso é a versão 18.12.1 necessária. Para confirmar a versão, execute o comando:

    node -v

    Se não for a versão certa, talvez seja necessário seguir as instruções de instalação Node.js nos pré-requisitos. Em seguida, reinicie o Node.js.

  • Depois de verificar se o Node.js necessário está em uso, execute este comando para instalar o vcremote sob essa versão do Node.js:

    npm install -g --unsafe-perm vcremote

    O comutador da instalação global (-g) é recomendado, mas não é obrigatório. Se você não usar o comutador de instalação global, o vcremote será instalado no caminho ativo atual no aplicativo Terminal.

    Durante a instalação, vcremote é instalado e o modo de desenvolvedor é ativado em seu Mac. Homebrew e dois pacotes npm, vcremote-lib e vcremote-utils, também são instalados. Após a conclusão da instalação, ignore os avisos sobre dependências opcionais ignoradas.

    Observação

    Para instalar o Homebrew, você deve ter acesso sudo (administrador). Se você precisa instalar o vcremote sem sudo, você pode instalar o Homebrew manualmente em um usr/local local e adicionar sua bin pasta ao seu caminho. Para obter mais informações, consulte a Documentação do Homebrew. Para habilitar manualmente o modo de desenvolvedor, digite este comando no aplicativo Terminal: DevToolsSecurity -enable

Se você atualizar para uma nova versão do Visual Studio, você deve atualizar para a versão atual do vcremote também. Para atualizar o vcremote, repita as etapas para baixar e instalar o agente remoto.

Iniciar vcremote

O agente remoto vcremote deve estar em execução para que o Visual Studio compile e execute seu código iOS. O Visual Studio deve ser emparelhado com vcremote antes de poder se comunicar. Por padrão, vcremote é executado no modo de conexão segura, que requer a transferência de certificados de cliente e servidor entre as máquinas Visual Studio e Mac.

Observação

A versão 1.0.19 ou posterior do vcremote requer pelo menos o Visual Studio 2022 versão 17.5.0 Preview 1 ou posterior. Se você estiver usando o Visual Studio 2022 versão 17.4 ou uma versão anterior, instale o vcremote versão 1.0.17.

Para iniciar o vcremote

  • No aplicativo Terminal no seu Mac, insira:

    vcremote

    Esse comando inicia o agente remoto com um diretório de build padrão de ~/vcremote. Para obter mais opções de configuração, consulte Configurar vcremote no Mac.

Na primeira vez que você iniciar o vcremote, e toda vez que você criar um novo certificado de servidor, você receberá as informações necessárias para configurar a conexão no Visual Studio. As informações incluem o nome do host e a porta. Se você pretende configurar o agente remoto no Visual Studio usando o nome do host, execute ping no Mac do Windows usando o nome do host para verificar se ele está acessível. Caso contrário, poderá ser necessário usar o endereço IP em vez disso.

É possível usar o agente remoto no modo desprotegido. No modo não seguro, o agente remoto pode ser emparelhado ao Visual Studio usando uma conexão HTTP simples que não criptografa dados. Use o modo não seguro por sua conta e risco. Recomendamos que você use um modo seguro para se conectar:

Visual Studio 2022 versão 17.5 e posterior com vcremote 1.0.19 e posterior:

No vcremote 1.0.19 e posterior, vcremote relata o caminho para um arquivo de server-cert.pem certificado, que deve ser carregado no Visual Studio.

Visual Studio 2022 versão 17.4 e versões anteriores com vcremote 1.0.17 e anteriores:

Versão 1.0.17 e versões mais antigas do vcremote geram um PIN para comunicação segura com versões do Visual Studio por meio do Visual Studio 2022 versão 17.4.

Screenshot of the Mac Terminal window that shows the host name, port, and PIN reported when VC remote is started.

O PIN gerado é de uso único e só é válido por um período limitado. Se você não emparelhar o Visual Studio com o agente remoto antes que o tempo expire, será necessário gerar um novo PIN. Para obter mais informações, consulte Gerar um novo PIN de segurança.

Para desabilitar o modo de conexão segura

  • Para desabilitar o modo de conexão segura no vcremote, digite este comando no aplicativo Terminal no seu Mac:

    vcremote --secure false

Para habilitar o modo de conexão segura

  • Para habilitar o modo de conexão segura, digite este comando:

    vcremote --secure true

Depois de iniciar o agente remoto, você pode usá-lo do Visual Studio até pará-lo.

Para parar o agente remoto

  • Na janela do Terminal em que o vcremote está em execução, insira Control+C.

Configurar vcremote no Visual Studio

Para se conectar ao agente remoto vcremote do Visual Studio, você deve especificar a configuração remota nas opções do Visual Studio. O Visual Studio usa as mesmas informações para se conectar ao agente remoto no seu Mac sempre que você usá-lo. Você não precisa emparelhar o Visual Studio com o agente remoto novamente, a menos que gere um novo certificado de segurança no Mac ou seu nome de host ou endereço IP seja alterado.

Para configurar o vcremote do Visual Studio 2022 versão 17.5 e posterior

  1. Se o agente ainda não estiver em execução no Mac, siga as etapas em Iniciar o agente remoto. Seu Mac deve estar executando vcremote para Visual Studio emparelhar, conectar e compilar seu projeto com êxito.

  2. No Mac, obtenha o nome do host ou o endereço IP do seu Mac.

    É possível obter o endereço IP usando o comando ifconfig em uma janela do Terminal. Use o inet endereço listado na interface de rede ativa.

  3. Na barra de menus do Visual Studio, escolha Opções de ferramentas>.

  4. Na caixa de diálogo Opções, expanda Cross Platform>C++>iOS.

  5. Nos campos Nome do Host e Porta, insira os valores especificados pelo agente remoto quando você o iniciou. O nome do host pode ser o nome DNS ou o endereço IP do seu Mac. A porta padrão é a 3030.

    Observação

    Se você não conseguir executar ping no Mac usando o nome do host, talvez seja necessário usar o endereço IP.

  6. Se você usar o agente remoto no modo de conexão segura padrão, marque a caixa de seleção Seguro e transfira o server-cert.pem arquivo do Mac para o Visual Studio para carregamento. Em seguida, escolha o botão Gerar para gerar um novo client-cert.pem arquivo, que deve aparecer na área de trabalho. Em seguida, transfira o certificado do cliente para o Mac em /vcremote/certs/Authorized-Clients. (Você pode transferir vários arquivos de certificado de cliente para esse diretório, para que várias máquinas autorizadas do Visual Studio possam enviar solicitações para este Mac.)

    Observação

    Se você estiver usando uma unidade USB para transferir certificados, exclua os certificados da unidade USB após a conclusão da transferência.

  7. Escolha Emparelhamento para habilitar o emparelhamento.

    Screenshot of the Tools Options dialog for iOS pairing. The host name, the port, the Secure checkbox, and the Remote Root values are set.

    O emparelhamento persiste até que você altere o nome do host, a porta ou gere um novo certificado de servidor ou cliente. Se você alterar o nome do host ou a porta na caixa de diálogo Opções , poderá escolher o botão Reverter para desfazer a alteração e reverter para o emparelhamento anterior.

    Se o emparelhamento não for bem-sucedido, verifique se o agente remoto está em execução seguindo as etapas em Iniciar o agente remoto. Siga as etapas para Gerar um novo certificado de servidor e Gerar um novo certificado de cliente. Se você estiver usando o nome do host do Mac, tente usar o endereço IP no campo Nome do host.

  8. Atualize o nome da pasta no campo Raiz Remota para especificar a pasta usada pelo agente remoto no diretório base (~) no Mac. Por padrão, o agente remoto usa /Users/<username>/vcremote como a raiz remota.

  9. Escolha OK para salvar as configurações de conexão de emparelhamento remoto.

Para configurar vcremote de versões anteriores ao Visual Studio 2022 versão 17.5

  1. Se o agente ainda não estiver em execução no Mac, siga as etapas em Iniciar o agente remoto. Seu Mac deve estar executando vcremote para Visual Studio emparelhar, conectar e compilar seu projeto com êxito.

  2. No Mac, obtenha o nome do host ou o endereço IP do seu Mac.

    É possível obter o endereço IP usando o comando ifconfig em uma janela do Terminal. Use o inet endereço listado na interface de rede ativa.

  3. Na barra de menus do Visual Studio, escolha Opções de ferramentas>.

  4. Na caixa de diálogo Opções, expanda Cross Platform>C++>iOS.

  5. Nos campos Nome do Host e Porta, insira os valores especificados pelo agente remoto quando você o iniciou. O nome do host pode ser o nome DNS ou o endereço IP do seu Mac. A porta padrão é a 3030.

    Observação

    Se não puder executar ping do Mac usando o nome do host, você precisará usar o endereço IP.

  6. Se você usar o agente remoto no modo de conexão segura padrão, marque a caixa de seleção Seguro e insira o valor do PIN especificado pelo agente remoto no campo Pin. Se você usar o agente remoto no modo de conexão não segura, desmarque a caixa de seleção Seguro e deixe o campo Pin em branco.

  7. Escolha Emparelhamento para habilitar o emparelhamento.

    Screenshot of the Tools Options dialog for iOS pairing. The host name, the port, the Secure checkbox, the pin, and the Remote Root values are set.

    O emparelhamento persiste até que você altere o nome do host ou a porta. Se você alterar o nome do host ou a porta na caixa de diálogo Opções, para desfazer a alteração, escolha o botão Reverter para reverter o emparelhamento anterior.

    Se o emparelhamento não for bem-sucedido, verifique se o agente remoto está em execução seguindo as etapas em Iniciar o agente remoto. Se tiver passado muito tempo desde que o PIN do agente remoto foi gerado, siga as etapas em Gerar um novo PIN de segurança. Em seguida, tente novamente. Se você estiver usando o nome do host do Mac, tente usar o endereço IP no campo Nome do host.

  8. Atualize o nome da pasta no campo Raiz Remota para especificar a pasta usada pelo agente remoto no diretório base (~) no Mac. Por padrão, o agente remoto usa /Users/<username>/vcremote como a raiz remota.

  9. Escolha OK para salvar as configurações de conexão de emparelhamento remoto.

Gerar um novo PIN de segurança

Aplica-se a: Visual Studio 2022 versão 17.4 e versões anteriores, usando vcremote versão 1.0.17 e anteriores.

Quando você inicia o agente remoto pela primeira vez, o PIN gerado é válido por um período limitado — por padrão, 10 minutos. Se você não emparelhar o Visual Studio com o agente remoto antes que o tempo expire, será necessário gerar um novo PIN.

Para gerar um novo PIN

  1. Pare o agente ou abra uma segunda janela do aplicativo Terminal no Mac e use-a para inserir o comando.

  2. Digite este comando no aplicativo Terminal:

    vcremote generateClientCert

    O agente remoto gera um novo PIN temporário. Para emparelhar o Visual Studio usando o novo PIN, repita as etapas em Configurar o agente remoto no Visual Studio.

Gerar um novo certificado de cliente

Aplica-se a: Visual Studio 2022 versão 17.5 e versões posteriores, usando vcremote versão 1.0.19 e posterior.

Ao emparelhar no Visual Studio, você gerará um novo client-cert.pem arquivo. Transfira o arquivo de certificado para a máquina de compilação do Mac em /vcremote/certs/Authorized-Clients. Esse certificado permite que o Mac autorize solicitações provenientes de sua máquina Visual Studio.

Gerar um novo certificado do servidor

Aplica-se a: Visual Studio 2022 versão 17.5 e versões posteriores, usando vcremote versão 1.0.19 e posterior.

Por motivos de segurança, os certificados de servidor que emparelham o Visual Studio ao agente remoto estão vinculados ao nome de host ou ao endereço IP do seu Mac. Se esses valores forem alterados, você precisará gerar um novo certificado do servidor e reconfigurar o Visual Studio com os novos valores.

Para gerar um novo certificado do servidor

  1. Interrompa o agente vcremote.

  2. Digite este comando no aplicativo Terminal:

    vcremote resetServerCert

  3. Quando for solicitado a confirmar, digite Y.

  4. Para emparelhar o Visual Studio com o Mac, transfira o arquivo recém-gerado server-cert.pem do Mac e carregue-o no Visual Studio, repetindo as etapas em Configurar o agente remoto no Visual Studio.

Configurar vcremote no Mac

É possível configurar o agente remoto usando várias opções de linha de comando. Por exemplo, você pode especificar a porta para escutar solicitações de compilação e especificar o número máximo de compilações a serem mantidas no sistema de arquivos. Por padrão, o limite é de 10 compilações. O agente remoto removerá as compilações que ultrapassarem o máximo no desligamento.

Para atualizar o agente remoto

  • Para ver uma lista completa dos comandos do agente remoto, no aplicativo Terminal, digite:

    vcremote --help

  • Para desabilitar o modo seguro e habilitar conexões simples baseadas em HTTP, digite:

    vcremote --secure false

    Ao usar essa opção, desmarque a caixa de seleção Proteger .

  • Para especificar um local para arquivos de agente remoto, digite:

    vcremote --serverDir directory_path

    Substitua directory_path pelo local no Mac para colocar arquivos de log, compilações e certificados de servidor. Por padrão, esse local é /Users/<username>/vcremote. As compilações são organizadas por número de build nesse local.

  • Para usar um processo em segundo plano para capturar stdout e stderr para um arquivo chamado server.log, digite:

    vcremote > server.log 2>&1 &

    O server.log arquivo pode ajudar a solucionar problemas de compilação.

  • Para executar o agente usando um arquivo de configuração em vez de parâmetros de linha de comando, digite:

    vcremote --config config_file_path

    Substitua config_file_path pelo caminho para um arquivo de configuração no formato JSON. As opções de inicialização e seus valores não devem incluir traços.

Solucionar problemas de agente remoto

Depuração em um dispositivo iOS

Se a depuração em um dispositivo iOS não funcionar, pode haver problemas com a ideviceinstaller ferramenta, que é usada para se comunicar com um dispositivo iOS. Essa ferramenta normalmente é instalada do Homebrew durante a instalação do vcremote. Siga as próximas etapas como uma solução alternativa:

Abra o aplicativo Terminal e atualize ideviceinstaller e suas dependências executando os seguintes comandos na ordem:

  1. Verifique se o Homebrew está atualizado

    brew update

  2. Desinstale libimobiledevice e usbmuxd

    brew uninstall --ignore-dependencies libimobiledevice

    brew uninstall --ignore-dependencies usbmuxd

  3. Instale a versão mais recente de libimobiledevice e usbmuxd

    brew install --HEAD usbmuxd

    brew unlink usbmuxd

    brew link usbmuxd

    brew install --HEAD libimobiledevice

  4. Desinstale e reinstale ideviceinstaller

    brew uninstall ideviceinstaller

    brew install ideviceinstaller

Verifique se o ideviceinstaller pode se comunicar com o dispositivo ao tentar listar os aplicativos instalados no dispositivo:

ideviceinstaller -l

Se ideviceinstaller relatar um erro de que ele não pode acessar a pasta /var/db/lockdown, altere o privilégio na pasta usando este comando:

sudo chmod 777 /var/db/lockdown

Em seguida, verifique novamente se ideviceinstaller poderá se comunicar com o dispositivo.

Confira também