Compartilhar via


Instalar ferramentas de build em um contêiner

Você pode instalar as Ferramentas de Build do Visual Studio em um contêiner do Windows para dar suporte a fluxos de trabalho de CI/CD (integração contínua e entrega contínua). Este artigo orienta você sobre quais alterações de configuração do Docker são necessárias, bem como quais cargas de trabalho e componentes você pode instalar em um contêiner.

contêineres são uma ótima maneira de empacotar um sistema de build consistente que você pode usar não apenas em um ambiente de servidor CI/CD, mas também em ambientes de desenvolvimento. Por exemplo, você pode montar seu código-fonte em um contêiner a ser criado por um ambiente personalizado enquanto continua a usar o Visual Studio ou outras ferramentas para escrever seu código. Se o fluxo de trabalho de CI/CD usar a mesma imagem de contêiner, você poderá ter certeza de que seu código é compilado de forma consistente. Você também pode usar contêineres para consistência durante o tempo de execução, o que é comum para microsserviços que utilizam vários contêineres com um sistema de orquestração; embora isso esteja além do escopo deste artigo.

Se as Ferramentas de Build do Visual Studio não tiverem o que você precisa para criar seu código-fonte, essas mesmas etapas poderão ser usadas para outros produtos do Visual Studio. Observe, no entanto, que os contêineres do Windows não dão suporte a uma interface do usuário interativa, portanto, todos os comandos devem ser automatizados.

Antes de começar

Alguma familiaridade com docker é assumida. Se você não estiver familiarizado com ele, saiba como instalar e configurar o mecanismo do Docker no Windows.

A imagem base a seguir é um exemplo e pode não funcionar para seu sistema. Leia de compatibilidade de versão do contêiner do Windows para determinar qual imagem base você deve usar para seu ambiente.

Criar e construir o Dockerfile

Salve o exemplo a seguir do Dockerfile em um novo arquivo em seu disco. Se o arquivo for nomeado simplesmente dockerfile, ele será reconhecido por padrão.

Aviso

Este exemplo do Dockerfile exclui apenas os SDKs anteriores do Windows que não podem ser instalados em contêineres. Versões anteriores fazem com que o comando de build falhe.

  1. Abra um prompt de comando.

  2. Criar um novo diretório (recomendado):

    mkdir C:\BuildTools
    
  3. Altere os diretórios para este novo diretório:

    cd C:\BuildTools
    
  4. Salve o conteúdo a seguir em C:\BuildTools\Dockerfile.

    # escape=`
    
    # Use the latest Windows Server Core 2019 image.
    FROM mcr.microsoft.com/windows/servercore:ltsc2019
    
    # Restore the default Windows shell for correct batch processing.
    SHELL ["cmd", "/S", "/C"]
    
    RUN `
        # Download the Build Tools bootstrapper.
        curl -SL --output vs_buildtools.exe https://aka.ms/vs/16/release/vs_buildtools.exe `
        `
        # Install Build Tools with the Microsoft.VisualStudio.Workload.AzureBuildTools workload, excluding workloads and components with known issues.
        && (start /w vs_buildtools.exe --quiet --wait --norestart --nocache `
            --installPath "%ProgramFiles(x86)%\Microsoft Visual Studio\2019\BuildTools" `
            --add Microsoft.VisualStudio.Workload.AzureBuildTools `
            --remove Microsoft.VisualStudio.Component.Windows10SDK.10240 `
            --remove Microsoft.VisualStudio.Component.Windows10SDK.10586 `
            --remove Microsoft.VisualStudio.Component.Windows10SDK.14393 `
            --remove Microsoft.VisualStudio.Component.Windows81SDK `
            || IF "%ERRORLEVEL%"=="3010" EXIT 0) `
        `
        # Cleanup
        && del /q vs_buildtools.exe
    
    # Define the entry point for the docker container.
    # This entry point starts the developer command prompt and launches the PowerShell shell.
    ENTRYPOINT ["C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\BuildTools\\Common7\\Tools\\VsDevCmd.bat", "&&", "powershell.exe", "-NoLogo", "-ExecutionPolicy", "Bypass"]
    

    Dica

    Para atingir 64 bits, especifique a opção -arch=amd64 no comando ENTRYPOINT para iniciar o Prompt de Comando do Desenvolvedor para Visual Studio (VSDevCmd.bat).

    Por exemplo: ENTRYPOINT ["C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\BuildTools\\Common7\\Tools\\VsDevCmd.bat", "-arch=amd64", "&&", "powershell.exe", "-NoLogo", "-ExecutionPolicy", "Bypass"]

    Aviso

    Se você basear sua imagem diretamente no microsoft/windowsservercore, o .NET Framework poderá não ser instalado corretamente e nenhum erro de instalação será indicado. O código gerenciado pode não ser executado após a conclusão da instalação. Em vez disso, baseie sua imagem em microsoft/dotnet-framework:4.8 ou uma versão mais recente. Observe também que as imagens marcadas como versão 4.8 ou posterior podem usar o PowerShell como o SHELLpadrão, podendo fazer com que as instruções RUN e ENTRYPOINT falhem.

    Para saber quais versões do sistema operacional de contêiner têm suporte em quais versões do sistema operacional host, consulte a compatibilidade de versão do contêiner do Windows . Verifique solução de problemas de contêineres do Windows e do Build Tools para problemas conhecidos.

    # escape=`
    
    # Use the latest Windows Server Core 2022 image.
    FROM mcr.microsoft.com/windows/servercore:ltsc2022
    
    # Restore the default Windows shell for correct batch processing.
    SHELL ["cmd", "/S", "/C"]
    
    RUN `
        # Download the Build Tools bootstrapper.
        curl -SL --output vs_buildtools.exe https://aka.ms/vs/17/release/vs_buildtools.exe `
        `
        # Install Build Tools with the Microsoft.VisualStudio.Workload.AzureBuildTools workload, excluding workloads and components with known issues.
        && (start /w vs_buildtools.exe --quiet --wait --norestart --nocache `
            --installPath "%ProgramFiles(x86)%\Microsoft Visual Studio\2022\BuildTools" `
            --add Microsoft.VisualStudio.Workload.AzureBuildTools `
            --remove Microsoft.VisualStudio.Component.Windows10SDK.10240 `
            --remove Microsoft.VisualStudio.Component.Windows10SDK.10586 `
            --remove Microsoft.VisualStudio.Component.Windows10SDK.14393 `
            --remove Microsoft.VisualStudio.Component.Windows81SDK `
            || IF "%ERRORLEVEL%"=="3010" EXIT 0) `
        `
        # Cleanup
        && del /q vs_buildtools.exe
    
    # Define the entry point for the docker container.
    # This entry point starts the developer command prompt and launches the PowerShell shell.
    ENTRYPOINT ["C:\\Program Files (x86)\\Microsoft Visual Studio\\2022\\BuildTools\\Common7\\Tools\\VsDevCmd.bat", "&&", "powershell.exe", "-NoLogo", "-ExecutionPolicy", "Bypass"]
    

    Dica

    Para atingir 64 bits, especifique a opção -arch=amd64 no comando ENTRYPOINT para iniciar o Prompt de Comando do Desenvolvedor para Visual Studio (VSDevCmd.bat).

    Por exemplo: ENTRYPOINT ["C:\\Program Files (x86)\\Microsoft Visual Studio\\2022\\BuildTools\\Common7\\Tools\\VsDevCmd.bat", "-arch=amd64", "&&", "powershell.exe", "-NoLogo", "-ExecutionPolicy", "Bypass"]

    Aviso

    Se você basear sua imagem diretamente no microsoft/windowsservercore, o .NET Framework poderá não ser instalado corretamente e nenhum erro de instalação será indicado. O código gerenciado pode não ser executado após a conclusão da instalação. Em vez disso, baseie sua imagem em microsoft/dotnet-framework:4.8 ou mais recente. Observe também que as imagens marcadas com a versão 4.8 ou posterior podem estar utilizando o PowerShell como SHELLpadrão, o que pode causar falhas nas instruções RUN e ENTRYPOINT.

    Para saber quais versões do sistema operacional de contêiner têm suporte em quais versões do sistema operacional host, consulte de compatibilidade de versão do contêiner do Windows. Verifique os containers de solução de problemas do Windows e do Build Tools para ver os problemas conhecidos.

    Nota

    O código de erro 3010 é usado para indicar sucesso, com a necessidade de uma reinicialização. Para obter mais informações, consulte MsiExec.exe mensagens de erro.

  5. Execute o comando a seguir dentro desse diretório.

    docker build -t buildtools2019:latest -m 2GB .
    

    Esse comando cria o Dockerfile no diretório atual usando 2 GB de memória. O padrão de 1 GB não é suficiente quando algumas cargas de trabalho são instaladas; no entanto, você pode ser capaz de criar com apenas 1 GB de memória, dependendo de seus requisitos de build.

    A imagem final é marcada buildtools2019:latest para que você possa executá-la facilmente em um contêiner como buildtools2019, pois a tag latest é o padrão se nenhuma tag for especificada. Se você quiser usar uma versão específica do Visual Studio Build Tools 2019 em um cenário mais avançado, poderá marcar o contêiner com um número de build específico do Visual Studio, bem como mais recente para que os contêineres possam usar uma versão específica de forma consistente.

    docker build -t buildtools:latest -m 2GB .
    

    Esse comando cria o Dockerfile no diretório atual usando 2 GB de memória. O padrão de 1 GB não é suficiente quando algumas cargas de trabalho são instaladas; no entanto, você pode ser capaz de criar com apenas 1 GB de memória, dependendo de seus requisitos de build.

    A imagem final é etiquetada buildtools:latest para que você possa executá-la facilmente em um contêiner como buildtools, já que a etiqueta mais recente é o padrão se nenhuma etiqueta for especificada. Se você quiser usar uma versão específica das Ferramentas de Build do Visual Studio em um cenário mais avançado, poderá marcar o contêiner com um número de build específico do Visual Studio, bem como mais recente para que os contêineres possam usar uma versão específica de forma consistente.

Usar a imagem criada

Agora que você criou uma imagem, você pode executá-la em um contêiner para fazer builds interativos e automatizados. O exemplo usa o Prompt de Comando do Desenvolvedor para que seu PATH e outras variáveis de ambiente já estejam configurados.

  1. Abra um prompt de comando.

  2. Execute o contêiner para iniciar um ambiente do PowerShell com todas as variáveis de ambiente do desenvolvedor definidas:

    docker run -it buildtools2019
    
    docker run -it buildtools
    

Para usar essa imagem para o fluxo de trabalho de CI/CD, você pode publicá-la em seu próprio Registro de Contêiner do Azure ou outro registro interno do Docker, e os servidores só precisam buscá-la.

Nota

Se o contêiner do Docker não for iniciado, provavelmente haverá um problema de instalação do Visual Studio. Você pode atualizar o Dockerfile para remover a etapa que chama o comando em lote do Visual Studio. Isso permite que você inicie o contêiner do Docker e leia os logs de erros de instalação.

No arquivo dockerfile, remova os parâmetros C:\\BuildTools\\Common7\\Tools\\VsDevCmd.bat e && do comando ENTRYPOINT. O comando agora deve ser ENTRYPOINT ["powershell.exe", "-NoLogo", "-ExecutionPolicy", "Bypass"]. Em seguida, recompile o Dockerfile e execute o comando run para acessar arquivos de contêiner. Para localizar os logs de erros de instalação, vá para o diretório $env:TEMP e localize o arquivo dd_setup_<timestamp>_errors.log.

Depois de identificar e corrigir o problema de instalação, você pode adicionar os parâmetros C:\\BuildTools\\Common7\\Tools\\VsDevCmd.bat e && de volta ao comando ENTRYPOINT e recompilar o Dockerfile.

Para obter mais informações, consulte Solução de problemas de contêineres do Windows e do Build Tools.

Solução de problemas de contêineres do Windows e do Build Tools

Há alguns problemas ao instalar o Visual Studio em um contêiner do Docker.

Solucionar problemas de contêineres do Windows

Os problemas conhecidos a seguir ocorrem quando você instala as Ferramentas de Build do Visual Studio em um contêiner do Windows.

  • Passe -m 2GB (ou mais) ao construir a imagem. Algumas cargas de trabalho exigem mais memória do que os 1 GB padrão quando instaladas.

  • Configure o Docker para usar discos maiores que os 20 GB padrão.

  • Passe --norestart na linha de comando. Até o momento desta escrita, a tentativa de reiniciar um contêiner Windows de dentro dele retorna ERROR_TOO_MANY_OPEN_FILES para o host.

  • Se você basear sua imagem diretamente em mcr.microsoft.com/windows/servercore, o .NET Framework poderá não ser instalado corretamente e nenhum erro de instalação será indicado. O código gerenciado pode não ser executado após a conclusão da instalação. Em vez disso, baseie sua imagem em microsoft/dotnet-framework:4.7.1 ou posterior. Por exemplo, você pode ver um erro ao compilar com o MSBuild semelhante ao seguinte:

    C:\BuildTools\MSBuild\15.0\bin\Roslyn\Microsoft.CSharp.Core.targets(84,5): erro MSB6003: O executável da tarefa especificada "csc.exe" não pôde ser executado. Não foi possível carregar o arquivo ou assembly 'System.IO.FileSystem, Version=4.0.1.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a' ou uma de suas dependências. O sistema não pode localizar o arquivo especificado.

Resolver problemas com contêineres das Ferramentas de Compilação

Os problemas conhecidos a seguir podem ocorrer quando você usa um contêiner de Ferramentas de Build. Para ver se os problemas foram corrigidos ou se há outros problemas conhecidos, visite da Comunidade de Desenvolvedores.

  • O IntelliTrace pode não funcionar em alguns cenários dentro de um contêiner.
  • Em versões mais antigas do Docker para Windows, o tamanho da imagem de contêiner padrão é de apenas 20 GB e não se encaixa em Ferramentas de Build. Siga as instruções para alterar o tamanho da imagem para 127 GB ou mais. Para confirmar um problema de espaço em disco, verifique os arquivos de log para obter mais informações. O arquivo vslogs\dd_setup_<timestamp>_errors.log inclui o seguinte se você ficar sem espaço em disco:
Pre-check verification: Visual Studio needs at least 91.99 GB of disk space. Try to free up space on C:\ or change your target drive.
Pre-check verification failed with error(s) :  SizePreCheckEvaluator.