Использование пакета SDK и средств .NET Core при непрерывной интеграции (CI)Using .NET Core SDK and tools in Continuous Integration (CI)

В этой статье описывается использование пакета SDK для .NET Core и входящих в него средств на сервере сборки.This document outlines using the .NET Core SDK and its tools on a build server. Набор инструментов .NET Core поддерживает два режима: интерактивный (разработчик вводит команды в командной строке) и автоматический (сервер непрерывной интеграции выполняет скрипт сборки).The .NET Core toolset works both interactively, where a developer types commands at a command prompt, and automatically, where a Continuous Integration (CI) server runs a build script. Команды, параметры, входные и выходные данные совпадают. В этом случае нужно только указать способ получения средств и систему сборки приложения.The commands, options, inputs, and outputs are the same, and the only things you supply are a way to acquire the tooling and a system to build your app. В этом документе рассматриваются сценарии ввода в эксплуатацию средства обеспечения непрерывной интеграции, а также рекомендации по разработке и структуре скриптов сборки.This document focuses on scenarios of tool acquisition for CI with recommendations on how to design and structure your build scripts.

Варианты установки для серверов сборки CIInstallation options for CI build servers

Использование собственных установщиковUsing the native installers

В macOS, Linux и Windows доступны собственные установщики.Native installers are available for macOS, Linux, and Windows. Установщики требуют доступа администратора (sudo) к серверу сборки.The installers require admin (sudo) access to the build server. Преимущество использования собственного установщика заключается в том, что он устанавливает собственные зависимости, необходимые для выполнения средства.The advantage of using a native installer is that it installs all of the native dependencies required for the tooling to run. Кроме того, собственные установщики обеспечивают системную установку пакета SDK.Native installers also provide a system-wide installation of the SDK.

Пользователи macOS должны использовать установщики PKG.macOS users should use the PKG installers. В случае с Linux можно выбрать диспетчер пакетов на основе каналов, например apt-get для Ubuntu или yum для CentOS. Кроме того, можно использовать сами пакеты (DEB или RPM).On Linux, there's a choice of using a feed-based package manager, such as apt-get for Ubuntu or yum for CentOS, or using the packages themselves, DEB or RPM. Для платформ Windows можно использовать установщик MSI.On Windows, use the MSI installer.

Последние надежные двоичные файлы можно найти на странице скачиваемых файлов .NET.The latest stable binaries are found at .NET downloads. Чтобы использовать последние (возможно, ненадежные) предварительные выпуски средств, воспользуйтесь ссылками в репозитории GitHub dotnet/core-sdk.If you wish to use the latest (and potentially unstable) pre-release tooling, use the links provided at the dotnet/core-sdk GitHub repository. Для дистрибутивов Linux также доступны архивы tar.gz (tarballs). Используйте вложенные в них скрипты, чтобы установить .NET Core.For Linux distributions, tar.gz archives (also known as tarballs) are available; use the installation scripts within the archives to install .NET Core.

Использование скрипта установкиUsing the installer script

Скрипт установки позволяет выполнять установку на сервере сборки без прав администратора. Кроме того, с его помощью очень легко обеспечить автоматизацию.Using the installer script allows for non-administrative installation on your build server and easy automation for obtaining the tooling. Скрипт самостоятельно скачивает средство и распаковывает его в стандартную или указанную папку.The script takes care of downloading the tooling and extracting it into a default or specified location for use. Вы также можете указать версию средства, которую следует установить, а также нужно ли установить пакет SDK целиком или только общую среду выполнения.You can also specify a version of the tooling that you wish to install and whether you want to install the entire SDK or only the shared runtime.

Работу скрипта установки можно автоматизировать в начале процесса сборки. Это позволяет получить и установить требуемую версию пакета SDK.The installer script is automated to run at the start of the build to fetch and install the desired version of the SDK. Требуемая версия — это версия пакета SDK, необходимая в проектах для сборки.The desired version is whatever version of the SDK your projects require to build. Этот скрипт позволяет установить пакет SDK в локальном каталоге на сервере, запустить средства из папки установки, а затем выполнить очистку после завершения сборки (очистку также может выполнить сервер непрерывной интеграции).The script allows you to install the SDK in a local directory on the server, run the tools from the installed location, and then clean up (or let the CI service clean up) after the build. Это обеспечивает инкапсуляцию и изоляцию процесса сборки.This provides encapsulation and isolation to your entire build process. Ссылку на скрипт установки можно найти в статье о dotnet-install.The installation script reference is found in the dotnet-install article.

Примечание

Azure DevOps ServicesAzure DevOps Services

При использовании скрипта установки собственные зависимости не устанавливаются автоматически.When using the installer script, native dependencies aren't installed automatically. Их необходимо установить вручную, если их нет в операционной системе.You must install the native dependencies if the operating system doesn't have them. Дополнительные сведения см. в статье Необходимые компоненты для .NET Core в Linux.For more information, see Prerequisites for .NET Core on Linux.

Примеры установки решений CICI setup examples

В этом разделе приведены сведения о ручной настройке с помощью скрипта PowerShell или bash, а также описано несколько решений SaaS для непрерывной интеграции,This section describes a manual setup using a PowerShell or bash script, along with a description of several software as a service (SaaS) CI solutions. таких как Travis CI, AppVeyor и Azure Pipelines.The SaaS CI solutions covered are Travis CI, AppVeyor, and Azure Pipelines.

Ручная настройкаManual setup

Каждая служба SaaS имеет собственные методы создания и настройки процесса сборки.Each SaaS service has its own methods for creating and configuring a build process. Если вы используете другое решения SaaS, нежели упомянутые выше, или хотите внести дополнительные изменения, конфигурацию необходимо выполнить вручную.If you use different SaaS solution than those listed or require customization beyond the pre-packaged support, you must perform at least some manual configuration.

Как правило, в процессе ручной настройки необходимо получить версию средства (или последнюю сборку) и выполнить скрипт сборки.In general, a manual setup requires you to acquire a version of the tools (or the latest nightly builds of the tools) and run your build script. Вы можете использовать скрипт PowerShell или bash, чтобы настроить команды .NET Core, а также файл проекта, который определяет процесс сборки.You can use a PowerShell or bash script to orchestrate the .NET Core commands or use a project file that outlines the build process. Подробные сведения об этих параметрах см. в разделе Оркестрация сборки.The orchestration section provides more detail on these options.

После создания сценария, выполняющего ручную настройку сервера сборки CI, проверьте его на локальном компьютере разработки.After you create a script that performs a manual CI build server setup, use it on your dev machine to build your code locally for testing purposes. Если проблем со скриптом не возникло, разверните его на сервере сборки CI.Once you confirm that the script is running well locally, deploy it to your CI build server. Ниже приведен относительно простой сценарий PowerShell, позволяющий получить пакет SDK для .NET Core и установить его на сервере сборки Windows.A relatively simple PowerShell script demonstrates how to obtain the .NET Core SDK and install it on a Windows build server:

$ErrorActionPreference="Stop"
$ProgressPreference="SilentlyContinue"

# $LocalDotnet is the path to the locally-installed SDK to ensure the
#   correct version of the tools are executed.
$LocalDotnet=""
# $InstallDir and $CliVersion variables can come from options to the
#   script.
$InstallDir = "./cli-tools"
$CliVersion = "1.0.1"

# Test the path provided by $InstallDir to confirm it exists. If it
#   does, it's removed. This is not strictly required, but it's a
#   good way to reset the environment.
if (Test-Path $InstallDir)
{
    rm -Recurse $InstallDir
}
New-Item -Type "directory" -Path $InstallDir

Write-Host "Downloading the CLI installer..."

# Use the Invoke-WebRequest PowerShell cmdlet to obtain the
#   installation script and save it into the installation directory.
Invoke-WebRequest `
    -Uri "https://dot.net/v1/dotnet-install.ps1" `
    -OutFile "$InstallDir/dotnet-install.ps1"

Write-Host "Installing the CLI requested version ($CliVersion) ..."

# Install the SDK of the version specified in $CliVersion into the
#   specified location ($InstallDir).
& $InstallDir/dotnet-install.ps1 -Version $CliVersion `
    -InstallDir $InstallDir

Write-Host "Downloading and installation of the SDK is complete."

# $LocalDotnet holds the path to dotnet.exe for future use by the
#   script.
$LocalDotnet = "$InstallDir/dotnet"

# Run the build process now. Implement your build script here.

Сведения о реализации процесса сборки следует указать в конце скрипта.You provide the implementation for your build process at the end of the script. Скрипт получает средства, а затем выполняет процесс сборки.The script acquires the tools and then executes your build process. Ниже приведен скрипт bash, который выполняет те же действия, что и описанный выше сценарий PowerShell, он выполняется на компьютерах UNIX.For UNIX machines, the following bash script performs the actions described in the PowerShell script in a similar manner:

#!/bin/bash
INSTALLDIR="cli-tools"
CLI_VERSION=1.0.1
DOWNLOADER=$(which curl)
if [ -d "$INSTALLDIR" ]
then
    rm -rf "$INSTALLDIR"
fi
mkdir -p "$INSTALLDIR"
echo Downloading the CLI installer.
$DOWNLOADER https://dot.net/v1/dotnet-install.sh > "$INSTALLDIR/dotnet-install.sh"
chmod +x "$INSTALLDIR/dotnet-install.sh"
echo Installing the CLI requested version $CLI_VERSION. Please wait, installation may take a few minutes.
"$INSTALLDIR/dotnet-install.sh" --install-dir "$INSTALLDIR" --version $CLI_VERSION
if [ $? -ne 0 ]
then
    echo Download of $CLI_VERSION version of the CLI failed. Exiting now.
    exit 0
fi
echo The CLI has been installed.
LOCALDOTNET="$INSTALLDIR/dotnet"
# Run the build process now. Implement your build script here.

Travis CITravis CI

Средство Travis CI можно настроить, чтобы установить пакет SDK для .NET Core с помощью языка csharp и ключа dotnet.You can configure Travis CI to install the .NET Core SDK using the csharp language and the dotnet key. Дополнительные сведения см. в официальной документации Travis CI по созданию проектов C#, F# или Visual Basic.For more information, see the official Travis CI docs on Building a C#, F#, or Visual Basic Project. Обратите внимание, что при доступе к сведениям сообщества Travis CI идентификатор языка language: csharp работает для всех языков .NET, в том числе F# и Mono.Note as you access the Travis CI information that the community-maintained language: csharp language identifier works for all .NET languages, including F#, and Mono.

Travis CI выполняет в матрице сборки как задания macOS, так и задания Linux. Вы можете указать сочетание среды выполнения, окружения, а также исключений и включений, чтобы охватить свои сочетания сборки приложения.Travis CI runs both macOS and Linux jobs in a build matrix, where you specify a combination of runtime, environment, and exclusions/inclusions to cover your build combinations for your app. Дополнительные сведения см. в статье о настройке сборки в документации по Travis CI.For more information, see the Customizing the Build article in the Travis CI documentation. Средства на основе MSBuild включают среды выполнения LTS (1.0.x) и текущие среды выполнения (1.1.x). Установив этот пакет SDK, вы получите все необходимые компоненты сборки.The MSBuild-based tools include the LTS (1.0.x) and Current (1.1.x) runtimes in the package; so by installing the SDK, you receive everything you need to build.

AppVeyorAppVeyor

Средство AppVeyor устанавливает рабочий образ сборки Visual Studio 2017 с пакетом SDK для .NET Core 1.0.1.AppVeyor installs the .NET Core 1.0.1 SDK with the Visual Studio 2017 build worker image. Доступны и другие образы сборки с разными версиями пакета SDK для .NET Core.Other build images with different versions of the .NET Core SDK are available. Дополнительные сведения см. в примере appveyor.yml и статье о рабочих образах сборки в документации по AppVeyor.For more information, see the appveyor.yml example and the Build worker images article in the AppVeyor docs.

Двоичные файлы пакета SDK для .NET Core загружаются в подкаталог и распаковываются в нем с помощью скрипта установки. Затем они добавляются в переменную среды PATH.The .NET Core SDK binaries are downloaded and unzipped in a subdirectory using the install script, and then they're added to the PATH environment variable. Добавьте матрицу сборки, чтобы выполнить тесты интеграции с разными версиями пакета SDK для .NET Core:Add a build matrix to run integration tests with multiple versions of the .NET Core SDK:

environment:
  matrix:
    - CLI_VERSION: 1.0.1
    - CLI_VERSION: Latest

install:
  # See appveyor.yml example for install script

Azure DevOps ServicesAzure DevOps Services

Настройте Azure DevOps Services, чтобы создавать проекты .NET Core, используя один из следующих подходов:Configure Azure DevOps Services to build .NET Core projects using one of these approaches:

  1. Выполнение скрипта из раздела Ручная настройка с использованием собственных команд.Run the script from the manual setup step using your commands.
  2. Создание сборки, состоящей из нескольких встроенных задач сборки Azure DevOps Services, которые используют средства .NET Core.Create a build composed of several Azure DevOps Services built-in build tasks that are configured to use .NET Core tools.

Оба решения допустимые.Both solutions are valid. С помощью скрипта ручной настройки можно управлять версиями средства, полученными в процессе сборки.Using a manual setup script, you control the version of the tools that you receive, since you download them as part of the build. Сборка выполняется с помощью скрипта, который необходимо создать.The build is run from a script that you must create. В этой статье описывается только создание вручную.This article only covers the manual option. Дополнительные сведения о создании сборки с помощью задач сборки Azure DevOps Services см. в документации по Azure Pipelines.For more information on composing a build with Azure DevOps Services build tasks, see the Azure Pipelines documentation.

Чтобы использовать скрипт ручной настройки в Azure DevOps Services, создайте определение сборки и укажите скрипт, выполняющий этап сборки.To use a manual setup script in Azure DevOps Services, create a new build definition and specify the script to run for the build step. Это можно сделать с помощью пользовательского интерфейса Azure DevOps Services:This is accomplished using the Azure DevOps Services user interface:

  1. Сначала создайте определение сборки.Start by creating a new build definition. Когда появится окно определения типа создаваемой сборки, выберите параметр Пусто.Once you reach the screen that provides you an option to define what kind of a build you wish to create, select the Empty option.

    Выбор пустого определения сборки

  2. После настройки репозитория сборки откроется окно "Определения сборок".After configuring the repository to build, you're directed to the build definitions. Выберите Добавить шаг сборки:Select Add build step:

    Добавление шага сборки

  3. После этого откроется каталог задач.You're presented with the Task catalog. В нем содержатся задачи, используемые в сборке.The catalog contains tasks that you use in the build. Так как у вас есть скрипт, нажмите кнопку Add (Добавить) рядом с параметром PowerShell: Run a PowerShell script (PowerShell: Запуск скрипта PowerShell).Since you have a script, select the Add button for PowerShell: Run a PowerShell script.

    Добавление этапа сценария PowerShell

  4. Настройте сервер сборки.Configure the build step. Добавьте скрипт из репозитория, для которого выполняется сборка:Add the script from the repository that you're building:

    Указание выполняемого сценария PowerShell

Оркестрация сборкиOrchestrating the build

Большая часть статьи посвящена тому, как получить средства .NET Core и настроить различные службы CI. Оркестрация или фактическое создание кода с помощью .NET Core до этого момента не упоминались.Most of this document describes how to acquire the .NET Core tools and configure various CI services without providing information on how to orchestrate, or actually build, your code with .NET Core. Способ структурирования процесса сборки зависит от многих факторов, которые нельзя здесь описать в общем виде.The choices on how to structure the build process depend on many factors that can't be covered in a general way here. Дополнительные сведения об оркестрации сборок на основе каждой упомянутой в этой статье технологии, а также ресурсы и примеры см. в документации по Travis CI, AppVeyor и Azure Pipelines.For more information on orchestrating your builds with each technology, explore the resources and samples provided in the documentation sets of Travis CI, AppVeyor, and Azure Pipelines.

Два принципиальных подхода структурирования процесса сборки кода .NET Core с использованием средств .NET Core заключаются в использовании MSBuild напрямую или с помощью программ командной строки .NET Core.Two general approaches that you take in structuring the build process for .NET Core code using the .NET Core tools are using MSBuild directly or using the .NET Core command-line commands. Выберите подход, который проще и удобнее для вас.Which approach you should take is determined by your comfort level with the approaches and trade-offs in complexity. MSBuild предоставляет возможность представить процесс сборки в виде задач и целевых объектов, но сложность этого подхода заключается в необходимости изучения синтаксиса файла проекта MSBuild.MSBuild provides you the ability to express your build process as tasks and targets, but it comes with the added complexity of learning MSBuild project file syntax. Подход с использованием программ командной строки .NET Core, возможно, проще, но в этом случае следует написать логику оркестрации на языке написания скриптов, например bash или PowerShell.Using the .NET Core command-line tools is perhaps simpler, but it requires you to write orchestration logic in a scripting language like bash or PowerShell.

См. такжеSee also