將 Build Tools 安裝至容器Install Build Tools into a container

您可以將 Visual Studio Build Tools 安裝至 Windows 容器,以便支援持續整合與持續傳遞 (CI/CD) 工作流程。You can install Visual Studio Build Tools into a Windows container to support continuous integration and continuous delivery (CI/CD) workflows. 本文將引導您了解需要進行的 Docker 組態變更,以及可在容器中安裝的工作負載和元件This article guides you through what Docker configuration changes are required as well as what workloads and components you can install in a container.

容器是用來封裝一致之建置系統的好方法,不僅可用於 CI/CD 伺服器環境,也可用於開發環境。Containers are a great way to package a consistent build system you can use not only in a CI/CD server environment but for development environments as well. 例如,您可以將原始程式碼裝載於容器中以供自訂環境建置,同時繼續使用 Visual Studio 或其他工具來撰寫程式碼。For example, you can mount your source code into a container to be built by a customized environment while you continue to use Visual Studio or other tools to write your code. 如果您的 CI/CD 工作流程使用相同的容器映像,就能確信您的程式碼會以一致的方式建置。If your CI/CD workflow uses the same container image, you can rest assured that your code builds consistently. 您也可以使用容器來取得執行階段一致性,此做法常見於使用具有一套協調流程系統之多個容器的微服務,但不在本文討論範圍內。You can use containers for runtime consistency as well, which is common for micro-services using multiple containers with an orchestration system; however, is beyond the scope of this article.

如果 Visual Studio Build Tools 沒有您建置原始程式碼所需的工具,這些相同步驟可用於其他 Visual Studio 產品。If Visual Studio Build Tools does not have what you require to build your source code, these same steps can be used for other Visual Studio products. 但請注意,Windows 容器不支援互動式使用者介面,因此所有命令都必須自動化。Do note, however, that Windows containers do not support an interactive user interface so all commands must be automated.

開始之前Before you begin

假設您已熟悉下列 Docker 功能。Some familiarity with Docker is assumed below. 若不熟悉如何在 Windows 上執行 Docker,請了解如何在 Windows 上安裝並設定 Docker 引擎 (部分機器翻譯)。If you're not already familiar with running Docker on Windows, read about how to install and configure the Docker engine on Windows.

下面的基底映像是範例,因此可能無法適用於您的系統。The base image below is a sample and may not work for your system. 閱讀 Windows 容器版本相容性以決定您應該為您的環境使用哪個基底映像。Read Windows container version compatibility to determine which base image you should use for your environment.

建立並建置 DockerfileCreate and build the Dockerfile

將下列範例 Dockerfile 儲存至磁碟上的新檔案。Save the following example Dockerfile to a new file on your disk. 如果檔案直接以 "Dockerfile" 命名,預設會辨識此名稱。If the file is named simply "Dockerfile", it is recognized by default.

警告

此範例 Dockerfile 只會排除無法安裝至容器的舊版 Windows SDK。This example Dockerfile excludes only earlier Windows SDKs that cannot be installed into containers. 較舊版本會造成建置命令失敗。Earlier releases cause the build command to fail.

  1. 開啟命令提示字元。Open a command prompt.

  2. 建立新的目錄 (建議):Create a new directory (recommended):

    mkdir C:\BuildTools
    
  3. 將目錄變更為此新目錄:Change directories to this new directory:

    cd C:\BuildTools
    
  4. 將下列內容儲存至 C:\BuildTools\Dockerfile。Save the following content to C:\BuildTools\Dockerfile.

    # escape=`
    
    # Use the latest Windows Server Core image with .NET Framework 4.7.2.
    FROM mcr.microsoft.com/dotnet/framework/sdk:4.7.2-windowsservercore-ltsc2019
    
    # Restore the default Windows shell for correct batch processing.
    SHELL ["cmd", "/S", "/C"]
    
    # Download the Build Tools bootstrapper.
    ADD https://aka.ms/vs/15/release/vs_buildtools.exe C:\TEMP\vs_buildtools.exe
    
    # Install Build Tools with the Microsoft.VisualStudio.Workload.AzureBuildTools workload, excluding workloads and components with known issues.
    RUN start /wait C:\TEMP\vs_buildtools.exe --quiet --wait --norestart --nocache `
        --installPath C:\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
    
    # Define the entry point for the Docker container.
    # This entry point starts the developer command prompt and launches the PowerShell shell.
    ENTRYPOINT ["C:\\BuildTools\\Common7\\Tools\\VsDevCmd.bat", "&&", "powershell.exe", "-NoLogo", "-ExecutionPolicy", "Bypass"]
    

    提示

    如需工作負載和元件的清單,請參閱 Visual Studio Build Tools 元件目錄For a list of workloads and components, see the Visual Studio Build Tools component directory.

    警告

    如果您是直接以 microsoft/windowsservercore 或 mcr.microsoft.com/windows/servercore 作為映像的基礎 (請參閱 Microsoft 同步發佈容器目錄 (英文)),.NET Framework 可能會無法正確安裝,且不會指出任何安裝錯誤。If you base your image directly on microsoft/windowsservercore or mcr.microsoft.com/windows/servercore (see Microsoft syndicates container catalog), the .NET Framework might not install properly and no install error is indicated. 安裝完成之後,可能無法執行受控碼。Managed code might not run after the install is complete. 相反地,讓您的映像以 microsoft/dotnet-framework:4.7.2 或更新版本為基礎。Instead, base your image on microsoft/dotnet-framework:4.7.2 or later. 另請注意,標記為 4.7.2 或更新版的映像可能會使用 PowerShell 作為預設 SHELL,導致 RUNENTRYPOINT 指令失敗。Also note that images that are tagged version 4.7.2 or later might use PowerShell as the default SHELL, which will cause the RUN and ENTRYPOINT instructions to fail.

    Visual Studio 2017 15.8 或更早版本 (任何產品) 無法在 mcr.microsoft.com/windows/servercore:1809 (或更新版本) 上正確安裝。Visual Studio 2017 version 15.8 or earlier (any product) will not properly install on mcr.microsoft.com/windows/servercore:1809 or later. 不會顯示錯誤。No error is displayed.

    請參閱 Windows 容器版本相容性 (部分機器翻譯) 以查看各種主機 OS 版本所支援的容器 OS 版本,並參閱容器的已知問題以了解已知問題。See Windows container version compatibility to see which container OS versions are supported on which host OS versions, and Known issues for containers for known issues.

    # escape=`
    
    # Use the latest Windows Server Core image with .NET Framework 4.8.
    FROM mcr.microsoft.com/dotnet/framework/sdk:4.8-windowsservercore-ltsc2019
    
    # Restore the default Windows shell for correct batch processing.
    SHELL ["cmd", "/S", "/C"]
    
    # Download the Build Tools bootstrapper.
    ADD https://aka.ms/vs/16/release/vs_buildtools.exe C:\TEMP\vs_buildtools.exe
    
    # Install Build Tools with the Microsoft.VisualStudio.Workload.AzureBuildTools workload, excluding workloads and components with known issues.
    RUN C:\TEMP\vs_buildtools.exe --quiet --wait --norestart --nocache `
        --installPath C:\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
    
    # Define the entry point for the docker container.
    # This entry point starts the developer command prompt and launches the PowerShell shell.
    ENTRYPOINT ["C:\\BuildTools\\Common7\\Tools\\VsDevCmd.bat", "&&", "powershell.exe", "-NoLogo", "-ExecutionPolicy", "Bypass"]
    

    提示

    如需工作負載和元件的清單,請參閱 Visual Studio Build Tools 元件目錄For a list of workloads and components, see the Visual Studio Build Tools component directory.

    警告

    如果您讓映像直接以 microsoft/windowsservercore 為基礎,.NET Framework 可能無法正確安裝且不會指出任何安裝錯誤。If you base your image directly on microsoft/windowsservercore, the .NET Framework might not install properly and no install error is indicated. 安裝完成之後,可能無法執行受控碼。Managed code might not run after the install is complete. 相反地,讓您的映像以 microsoft/dotnet-framework:4.8 或更新版本為基礎。Instead, base your image on microsoft/dotnet-framework:4.8 or later. 另請注意,標記為 4.8 或更新版的映像可能會使用 PowerShell 作為預設 SHELL,導致 RUNENTRYPOINT 指令失敗。Also note that images that are tagged version 4.8 or later might use PowerShell as the default SHELL, which will cause the RUN and ENTRYPOINT instructions to fail.

    請參閱 Windows 容器版本相容性 (部分機器翻譯) 以查看各種主機 OS 版本所支援的容器 OS 版本,並參閱容器的已知問題以了解已知問題。See Windows container version compatibility to see which container OS versions are supported on which host OS versions, and Known issues for containers for known issues.

    注意

    錯誤碼 3010 可用來表示成功,需要重新開機,請參閱 MsiExec.exe 錯誤訊息 以取得詳細資訊。Error code 3010 is used to indicate success with a reboot required, see MsiExec.exe error messages for more information.

  5. 從該目錄內執行下列命令。Run the following command within that directory.

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

    此命令使用 2 GB 的記憶體在目前的目錄中建置 Dockerfile。This command builds the Dockerfile in the current directory using 2 GB of memory. 安裝某些工作負載時,預設 1 GB 並不夠;不過,根據您的建置需求,您可能只使用 1 GB 記憶體就能夠進行建置。The default 1 GB is not sufficient when some workloads are installed; however, you might be able to build with only 1 GB of memory depending on your build requirements.

    最終映像會標記為 "buildtools2017:latest",因此您可以輕鬆地在容器中當作 "buildtools2017" 來執行 (因為 "latest" 是未指定任何標記時的預設值)。The final image is tagged "buildtools2017:latest" so you can easily run it in a container as "buildtools2017" since the "latest" tag is the default if no tag is specified. 如果您想要在更進階的案例中使用特定版本的 Visual Studio Build Tools 2017,請改以特定 Visual Studio 組建編號及 "latest" 來標記容器,以確保容器能夠一致地使用特定版本。If you want to use a specific version of Visual Studio Build Tools 2017 in a more advanced scenario, you might instead tag the container with a specific Visual Studio build number as well as "latest" so containers can use a specific version consistently.

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

    此命令使用 2 GB 的記憶體在目前的目錄中建置 Dockerfile。This command builds the Dockerfile in the current directory using 2 GB of memory. 安裝某些工作負載時,預設 1 GB 並不夠;不過,根據您的建置需求,您可能只使用 1 GB 記憶體就能夠進行建置。The default 1 GB is not sufficient when some workloads are installed; however, you might be able to build with only 1 GB of memory depending on your build requirements.

    最終映像會標記為 "buildtools2019:latest",因此您可以輕鬆地在容器中當作 "buildtools2019" 來執行 (因為 "latest" 是未指定任何標記時的預設)。The final image is tagged "buildtools2019:latest" so you can easily run it in a container as "buildtools2019" since the "latest" tag is the default if no tag is specified. 如果您想要在更進階的案例中使用特定版本 Visual Studio Build Tools 2019,請改以特定 Visual Studio 組建編號及 "latest" 來標記容器,以確保容器能夠一致地使用特定版本。If you want to use a specific version of Visual Studio Build Tools 2019 in a more advanced scenario, you might instead tag the container with a specific Visual Studio build number as well as "latest" so containers can use a specific version consistently.

使用建置的映像Using the built image

現在您已建立映像,您可以在容器中執行,以同時執行互動式和自動化組建。Now that you have created an image, you can run it in a container to do both interactive and automated builds. 此範例使用開發人員命令提示字元,因此已設定您的 PATH 和其他環境變數。The example uses the Developer Command Prompt, so your PATH and other environment variables are already configured.

  1. 開啟命令提示字元。Open a command prompt.

  2. 執行容器,以啟動 PowerShell 環境並設定所有開發人員環境變數:Run the container to start a PowerShell environment with all developer environment variables set:

    docker run -it buildtools2017
    
    docker run -it buildtools2019
    

若要將此映像用於您的 CI/CD 工作流程,您可以將其發佈至自己的 Azure 容器登錄或其他內部 Docker 登錄,讓伺服器只需要加以提取。To use this image for your CI/CD workflow, you can publish it to your own Azure Container Registry or other internal Docker registry so servers need only to pull it.

注意

如果 Docker 容器無法啟動,可能是 Visual Studio 安裝問題。If the Docker container fails to start, there's likely a Visual Studio installation issue. 您可以更新 Dockerfile,以移除呼叫 Visual Studio 批次命令的步驟。You can update the Dockerfile to remove the step that calls the Visual Studio batch command. 這可讓您啟動 Docker 容器,並讀取安裝錯誤記錄檔。This enables you to start the Docker container and read the installation error logs.

在 Dockerfile 檔案中, C:\\BuildTools\\Common7\\Tools\\VsDevCmd.bat && 從命令移除和參數 ENTRYPOINTIn your Dockerfile file, remove the C:\\BuildTools\\Common7\\Tools\\VsDevCmd.bat and && parameters from the ENTRYPOINT command. 命令現在應該是 ENTRYPOINT ["powershell.exe", "-NoLogo", "-ExecutionPolicy", "Bypass"]The command should now be ENTRYPOINT ["powershell.exe", "-NoLogo", "-ExecutionPolicy", "Bypass"]. 接下來,重建 Dockerfile 並執行 run 命令以存取容器檔案。Next, rebuild the Dockerfile and execute the run command to access container files. 若要找出安裝錯誤記錄檔,請移至 $env:TEMP 目錄並找出檔案 dd_setup_<timestamp>_errors.logTo locate the installation error logs, go to the $env:TEMP directory and locate the dd_setup_<timestamp>_errors.log file.

找出並修正安裝問題之後,您可以將 C:\\BuildTools\\Common7\\Tools\\VsDevCmd.bat 和參數新增 &&ENTRYPOINT 命令,並重建您的 Dockerfile。After you identify and fix the installation issue, you can add the C:\\BuildTools\\Common7\\Tools\\VsDevCmd.bat and && parameters back to the ENTRYPOINT command and rebuild your Dockerfile.

如需詳細資訊,請參閱容器的已知問題For more information, see Known issues for containers.

取得支援Get support

有時可能會發生一些問題。Sometimes, things can go wrong. 若 Visual Studio 安裝失敗,請參閱針對 Visual Studio 安裝和升級問題進行疑難排解,以取得逐步指導方針。If your Visual Studio installation fails, see Troubleshoot Visual Studio installation and upgrade issues for step-by-step guidance.

我們也提供 安裝聊天 (僅限英文) 支援選項,可回答安裝的相關問題。We also offer an installation chat (English only) support option for installation-related issues.

以下是一些支援選項:Here are a few more support options:

另請參閱See also