Usando TeamCity com Xamarin

  • Artigo

Este guia discutirá as etapas envolvidas no uso do TeamCity para compilar aplicativos móveis e, em seguida, enviá-los ao Teste do App Center.

Conforme discutido no guia de Introdução à Integração Contínua, a integração contínua (CI) é uma prática útil ao desenvolver aplicativos móveis de qualidade. Existem muitas opções viáveis para software de servidor de integração contínua; este guia se concentrará no TeamCity da JetBrains.

Existem várias permutações diferentes de uma instalação do TeamCity. A lista a seguir descreve algumas dessas permutações:

  • Serviço do Windows – Nesse cenário, o TeamCity é iniciado quando o Windows é inicializado como um Serviço do Windows. Ele deve ser emparelhado com um Mac Build Host para compilar quaisquer aplicativos iOS.

  • Iniciar o Daemon no OS X – Conceitualmente, isso é semelhante à execução como um serviço do Windows descrito na etapa anterior. Por padrão, as compilações serão executadas na conta raiz.

  • Conta de usuário no OS X – É possível executar o TeamCity em uma conta de usuário que é iniciada sempre que o usuário faz login.

Dos cenários anteriores, executar o TeamCity em uma conta de usuário no OS X é o mais simples e fácil de configurar.

Há várias etapas envolvidas na configuração do TeamCity:

  • Instalando o TeamCity – A instalação do TeamCity não é abordada neste guia. Este guia pressupõe que o TeamCity esteja instalado e em execução em uma conta de usuário. As instruções sobre como instalar o TeamCity podem ser encontradas na documentação do TeamCity 8 pela JetBrains.

  • Preparando o servidor de compilação – Esta etapa envolve a instalação do software, as ferramentas e os certificados necessários para criar aplicativos móveis e prepará-los para distribuição.

  • Criando um script de compilação – Esta etapa não é estritamente necessária, mas um script de compilação é uma ajuda útil para criar aplicativos autônomos. O uso de um script de compilação ajudará na solução de problemas de compilação que possam surgir e fornecerá uma maneira consistente e repetível de criar os binários para distribuição, mesmo que a integração contínua não seja praticada.

  • Criando um projeto TeamCity – Depois que as três etapas anteriores forem concluídas, devemos criar um projeto TeamCity que conterá todos os metadados necessários para recuperar o código-fonte, compilar os projetos e enviar os testes para o App Center Test.

Requisitos

É necessário ter experiência com o App Center Test .

É necessário ter familiaridade com o TeamCity 8.1. A instalação do TeamCity está além do escopo deste documento. Presume-se que o TeamCity está instalado no OS X Mavericks e está sendo executado em uma conta de usuário regular e não na conta root.

O servidor de compilação deve ser um computador autônomo, executando o OS X, dedicado à integração contínua. Idealmente, o servidor de compilação não será responsável por outras funções, como um servidor de banco de dados, servidor Web ou estação de trabalho do desenvolvedor.

Importante

Este guia não cobre uma instalação "sem cabeça" do Xamarin.

Configuração do firewall

Para que os testes sejam enviados ao Xamarin Test Cloud, o computador que os envia deve ser capaz de se comunicar com os servidores do Test Cloud. Os firewalls devem ser configurados para permitir o tráfego de rede de e para os servidores localizados em testcloud.xamarin.com nas portas 80 e 443. Esse ponto de extremidade é gerenciado pelo DNS e o endereço IP está sujeito a alterações.

Em algumas situações, um teste (ou um dispositivo executando o teste) deve se comunicar com servidores Web protegidos por um firewall. Nesse cenário, o firewall deve ser configurado para permitir o tráfego dos seguintes endereços IP:

  • 195.249.159.238
  • 195.249.159.239

Preparando o servidor de compilação

Uma etapa crucial na configuração de um servidor de compilação é instalar todas as ferramentas, software e certificados necessários para criar os aplicativos móveis. É importante que o servidor de compilação possa compilar a solução móvel e executar quaisquer testes. Para minimizar problemas de configuração, o software e as ferramentas devem ser instalados na mesma conta de usuário que está hospedando o TeamCity. A lista a seguir detalha o que é necessário:

  1. Visual Studio para Mac – Isso inclui Xamarin.iOS e Xamarin.Android.
  2. Efetuar login no Repositório de Componentes Xamarin – Esta etapa é opcional e necessária somente se seu aplicativo usar Componentes do Repositório de Componentes Xamarin. O login proativo no repositório de componentes neste ponto evitará quaisquer problemas quando uma compilação do TeamCity tentar compilar o aplicativo.
  3. Xcode – Xcode é necessário para compilar e assinar aplicativos iOS.
  4. Ferramentas de linha de comando do Xcode – Isso é descrito na etapa 1 da seção Instalação do guia Atualizando Ruby com rbenv .
  5. Assinando identidade e perfis de provisionamento – importe os certificados e o perfil de provisionamento via XCode. Consulte o guia da Apple sobre como exportar identidades de assinatura e perfis de provisionamento para obter mais detalhes.
  6. Android Keystores – Copie os keystores Android necessários para um diretório ao qual o usuário do TeamCity tem acesso, ou seja ~/Documents/keystores/MyAndroidApp1, .
  7. Calabash – Esta é uma etapa opcional se seu aplicativo tiver testes escritos usando Calabash. Consulte o guia Instalando o Calabash no OS X Mavericks e o guia Atualizando o Ruby com rbenv para obter mais informações.

O diagrama a seguir ilustra todos esses componentes:

This diagram illustrates all of these components

Depois que todo o software estiver instalado, faça login na conta de usuário e confirme se todo o software está instalado e funcionando corretamente. Isso deve envolver a compilação da solução e o envio do aplicativo ao Teste do App Center. Isso pode ser simplificado executando o script de compilação, conforme descrito na próxima seção.

Criar um script de compilação

Embora seja possível para o TeamCity lidar com todos os aspectos de compilação e envio de aplicativos móveis para o App Center Test por si só; É recomendável criar um script de compilação. Um script de compilação fornece as seguintes vantagens:

  1. Documentação – Um script de compilação serve como uma forma de documentação sobre como o software é construído. Isso remove parte da "magia" associada à implantação do aplicativo e permite que os desenvolvedores se concentrem na funcionalidade.
  2. Repetibilidade – Um script de compilação garante que cada vez que o aplicativo é compilado e implantado, ele acontece da mesma maneira, independentemente de quem ou o que faz o trabalho. Essa consistência repetível remove quaisquer problemas ou erros que possam aparecer devido a uma compilação executada incorretamente ou erro humano.
  3. Controle de versão – Um script de compilação pode ser incluído no sistema de controle do código-fonte . Isso significa que as alterações no script de compilação podem ser rastreadas, monitoradas e corrigidas se erros ou imprecisões forem encontrados.
  4. Preparar o ambiente – Um script de compilação pode incluir lógica para instalar quaisquer dependências de terceiros 3rd necessárias. Isso garantirá que os aplicativos sejam criados com os componentes adequados.

O script de compilação pode ser tão simples quanto um arquivo do PowerShell (no Windows) ou um script bash (no OS X). Ao criar o script de compilação, há várias opções para linguagens de script:

  • Rake – esta é uma DSL (Domain-Specific Language) para projetos de construção, baseada em Ruby. Rake tem a vantagem da popularidade e um rico ecossistema de bibliotecas.

  • psake – esta é uma biblioteca do Windows PowerShell para criar software

  • FAKE – esta é uma DSL baseada em F# que torna possível usar bibliotecas .NET existentes, se necessário.

A linguagem de script usada depende de suas preferências e requisitos.

Observação

É possível usar um sistema de compilação baseado em XML, como MSBuild ou NAnt, mas estes não têm a expressividade e a capacidade de manutenção de uma DSL dedicada à construção de software.

Parametrizando o script de compilação

O processo de construção e teste de software requer informações que devem ser mantidas em segredo. Criar um APK pode exigir uma senha para o keystore e/ou o alias de chave no keystore. Da mesma forma, o Teste do App Center requer uma chave de API exclusiva para um desenvolvedor. Esses tipos de valores não devem ser codificados no script de compilação. Em vez disso, eles devem ser passados como variáveis para o script de compilação.

Menos sensíveis são valores como o ID do dispositivo iOS ou o ID do dispositivo Android que identificam quais dispositivos o App Center deve usar para execuções de teste. Esses não são valores que precisam ser protegidos, mas podem mudar de compilação para compilação.

Armazenar esses tipos de variáveis fora do script de compilação também facilita o compartilhamento do script de compilação dentro de uma organização, com desenvolvedores, por exemplo. Os desenvolvedores podem usar exatamente o mesmo script que o servidor de compilação, mas podem usar seus próprios keystores e chaves de API.

Há duas opções possíveis para armazenar esses valores confidenciais:

  • Um arquivo de configuração – Para proteger a chave da API, esse valor não deve ser verificado no controle de versão. O arquivo pode ser criado para cada máquina. A forma como os valores são lidos a partir deste ficheiro depende da linguagem de script utilizada.

  • Variáveis de ambiente – elas podem ser facilmente definidas por máquina e são independentes da linguagem de script subjacente.

Há vantagens e desvantagens em cada uma dessas escolhas. O TeamCity funciona bem com variáveis de ambiente, portanto, este guia recomendará essa técnica ao criar scripts de compilação.

Etapas de compilação

O script de compilação deve executar as seguintes etapas:

  • Compilar o aplicativo – Isso inclui assinar o aplicativo com o perfil de provisionamento correto.

  • Enviar o aplicativo para o Xamarin Test Cloud – Isso inclui assinar e compactar o APK com o keystore apropriado.

Essas duas etapas serão explicadas com mais detalhes a seguir.

Compilando um aplicativo Xamarin.iOS

A linha de comando a seguir para especificar uma compilação Release da solução SOLUTION_FILE.sln para o iPhone. O local do IPA pode ser definido especificando a IpaPackageDir propriedade na linha de comando:

  • No Mac, usando xbuild:

    xbuild /p:Configuration="Release" \ 
       /p:Platform="iPhone" \ 
       /p:IpaPackageDir="$HOME/Builds" \
       /t:Build MyProject.sln

O comando xbuild é normalmente encontrado no diretório /Library/Frameworks/Mono.framework/Commands.

  • No Windows, usando msbuild:

    msbuild /p:Configuration="Release" 
        /p:Platform="iPhone" 
        /p:IpaPackageDir="%USERPROFILE%\Builds" 
        /p:ServerAddress="192.168.1.3" /p:ServerUser="macuser"  
        /t:Build MyProject.sln

O MSBuid não expandirá $( ) automaticamente as expressões passadas pela linha de comando. Por esse motivo, é recomendável usar um caminho completo ao definir o IpaPackageDir na linha de comando.

Consulte as Notas de versão do iOS 9.8 para obter mais detalhes sobre a IpaPackageDir propriedade.

Compilando um aplicativo Xamarin.Android

Para compilar um aplicativo Android, use xbuild (ou msbuild no Windows):

/Library/Frameworks/Mono.framework/Commands/xbuild /t:SignAndroidPackage /p:Configuration=Release /path/to/android.csproj

A compilação do aplicativo Android xbuild usa o projeto, enquanto o aplicativo iOS xbuild usa a solução.

Enviando Xamarin.UITests para o App Center

As UITests são enviadas usando a CLI do App Center, conforme mostrado no trecho a seguir:

appcenter test run uitest --app <TEAM-NAME/APP-NAME> --devices <DEVICE_SET> --token <API_KEY> --app-path <appname.APK-or-appname.IPA> --merge-nunit-xml report.xml --build-dir pathToUITestBuildDir

Quando o teste é executado, os resultados do teste serão retornados na forma de um arquivo XML estilo NUnit chamado report.xml. O TeamCity exibirá as informações no Log de compilação.

Para obter mais informações sobre como enviar UITests para o App Center, consulte Preparando aplicativos Xamarin.Android ou Preparando aplicativos Xamarin.iOS.

Enviando testes do Calabash para o App Center

Os testes do Calabash são enviados usando a CLI do App Center, conforme mostrado no trecho a seguir:

appcenter test run calabash --app <TEAM-NAME/APP-NAME> --devices <DEVICE_SET> --token <API_KEY> --app-path <appname.APK-or-appname.IPA> --project-dir pathToProjectDir

Para enviar um aplicativo Android para o App Center Test, é necessário primeiro reconstruir o servidor de teste APK usando calabash-android:

$ calabash-android build </path/to/signed/APK>
$ appcenter test run calabash --app <TEAM-NAME/APP-NAME> --devices <DEVICE_SET> --token <API_KEY> --app-path <appname.APK> --project-dir pathToProjectDir

Para obter mais informações sobre como enviar testes Calabash, consulte o guia do Xamarin sobre como enviar testes Calabash para o Test Cloud.

Criando um projeto TeamCity

Depois que o TeamCity estiver instalado e o Visual Studio para Mac puder criar seu projeto, é hora de criar um projeto no TeamCity para compilar o projeto e enviá-lo ao App Center.

  1. Iniciado fazendo login no TeamCity através do navegador da web. Navegue até o projeto raiz:

    Navigate to the Root Project Abaixo do projeto raiz, crie um novo subprojeto:

    Navigate to the Root Project Underneath the Root Project, create a new subproject

  2. Depois que o subprojeto for criado, adicione uma nova configuração de compilação:

    Once the subproject is created, add a new Build Configuration

  3. Anexe um projeto VCS à configuração de compilação. Isso é feito através da tela Configuração do Controle de Versão:

    This is done via the Version Control Setting screen

    Se não houver nenhum projeto VCS criado, você pode criar um a partir da página Nova raiz do VCS mostrada abaixo:

    If there's no VCS project created, you can create one from the New VCS Root page

    Depois que a raiz VCS tiver sido anexada, o TeamCity verificará o projeto e tentará detectar automaticamente as etapas de compilação. Se você estiver familiarizado com o TeamCity, poderá selecionar uma das etapas de compilação detectadas. É seguro ignorar as etapas de compilação detectadas por enquanto.

  4. Em seguida, configure um gatilho de compilação. Isso enfileirará uma compilação quando determinadas condições forem atendidas, como quando um usuário confirma o código no repositório. A captura de tela a seguir mostra como adicionar um gatilho de compilação:

    This screenshot shows how to add a build trigger Um exemplo de configuração de um gatilho de compilação pode ser visto na captura de tela a seguir:

    An example of configuring a build trigger can be seen in this screenshot

  5. A seção anterior, Parametrizando o script de compilação, sugeriu armazenar alguns valores como variáveis de ambiente. Essas variáveis podem ser adicionadas à configuração de compilação através da tela Parâmetros. Adicione as variáveis para a chave de API do App Center, a ID do dispositivo iOS e a ID do dispositivo Android, conforme mostrado na captura de tela abaixo:

    Add the variables for the App Center Test API Key, the iOS device ID, and the Android Device ID

  6. A etapa final é adicionar uma etapa de compilação que invocará o script de compilação para compilar o aplicativo e enfileirar o aplicativo para o Teste do App Center. A captura de tela a seguir é um exemplo de uma etapa de compilação que usa um Rakefile para criar um aplicativo:

    This screenshot is an example of a build step that uses a Rakefile to build an application

  7. Neste ponto, a configuração de compilação está concluída. É uma boa ideia acionar uma compilação para confirmar que o projeto está configurado corretamente. Uma boa maneira de fazer isso é confirmar uma pequena e insignificante alteração no repositório. O TeamCity deve detectar a confirmação e iniciar uma compilação.

  8. Depois que a compilação for concluída, inspecione o log de compilação e veja se há algum problema ou aviso com a compilação que exija atenção.

Resumo

Este guia abordou como usar o TeamCity para criar aplicativos Xamarin Mobile e, em seguida, enviá-los para o Teste do App Center. Discutimos a criação de um script de compilação para automatizar o processo de compilação. O script de compilação se encarrega de compilar o aplicativo, enviar para o Teste do App Center e aguardar os resultados.

Em seguida, abordamos como criar um projeto no TeamCity que enfileirará uma compilação cada vez que um desenvolvedor confirmar o código e chamará o script de compilação.