diff --git a/.travis.yml b/.travis.yml index 7f1ac5edee6d8..3cddb3c95e941 100644 --- a/.travis.yml +++ b/.travis.yml @@ -9,11 +9,21 @@ matrix: - os: osx # OSX 10.11 osx_image: xcode7.2 dotnet: 1.0.0-preview2-003121 + - os: osx # OSX 10.12 + osx_image: xcode7.3 + dotnet: 1.0.0-rc4-0044771 + +## If `dotnet` configuration doesnt work, use install script instead +# install: +# - export DOTNET_INSTALL_DIR="$PWD/.dotnetsdk" +# - curl -sSL https://raw.githubusercontent.com/dotnet/cli/rel/1.0.0/scripts/obtain/dotnet-install.sh | bash /dev/stdin --version "$CLI_VERSION" --install-dir "$DOTNET_INSTALL_DIR" +# - export PATH="$DOTNET_INSTALL_DIR:$PATH" script: + - dotnet --info # Run a new console app - mkdir -p "test/test-dotnet-new" && pushd "test/test-dotnet-new" - dotnet new - dotnet restore - - dotnet --verbose run a b + - dotnet run a b - popd diff --git a/appveyor.yml b/appveyor.yml index e10e6e007dbf1..94a8d642d46da 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -1,33 +1,27 @@ os: Visual Studio 2015 -## .NET Core SDK preview1 is already installed in the build worker image Visual Studio 2015 -## -## To install a specific version: -## -## install: -## # .NET Core SDK binaries -## ## 1) from direct url -## - ps: $url = "https://go.microsoft.com/fwlink/?LinkID=798402" # v1.0.0-preview1 x64 -## ## 2) from url based on version, for example using an env var CLI_VERSION that can be a -## ## a specific version `1.0.0-preview2-003121` or `Latest` (for latest dev version) -## - ps: $url = "https://dotnetcli.blob.core.windows.net/dotnet/preview/Binaries/$($env:CLI_VERSION)/dotnet-dev-win-x64.$($env:CLI_VERSION.ToLower()).zip" -## # Download .NET Core SDK and add to PATH -## - ps: $env:DOTNET_INSTALL_DIR = "$pwd\.dotnetsdk" -## - ps: mkdir $env:DOTNET_INSTALL_DIR -Force | Out-Null -## - ps: $tempFile = [System.IO.Path]::GetTempFileName() -## - ps: (New-Object System.Net.WebClient).DownloadFile($url, $tempFile) -## - ps: Add-Type -AssemblyName System.IO.Compression.FileSystem; [System.IO.Compression.ZipFile]::ExtractToDirectory($tempFile, $env:DOTNET_INSTALL_DIR) -## - ps: $env:Path = "$env:DOTNET_INSTALL_DIR;$env:Path" +# NOTE .NET Core SDK preview2 is already installed in the build worker image Visual Studio 2015 +# so the `install` section is not required + +environment: + CLI_VERSION: 1.0.0-rc4-004771 + +install: + - ps: $env:DOTNET_INSTALL_DIR = "$pwd\.dotnetsdk" + - ps: mkdir $env:DOTNET_INSTALL_DIR -Force | Out-Null + - ps: Invoke-WebRequest -Uri "https://raw.githubusercontent.com/dotnet/cli/rel/1.0.0/scripts/obtain/dotnet-install.ps1" -OutFile "$($env:DOTNET_INSTALL_DIR)/dotnet-install.ps1" + - ps: '& "$($env:DOTNET_INSTALL_DIR)/dotnet-install.ps1" -Version $env:CLI_VERSION -InstallDir $env:DOTNET_INSTALL_DIR' + - ps: $env:Path = "$env:DOTNET_INSTALL_DIR;$env:Path" build_script: # dotnet info - ps: dotnet --info # Run dotnet new - ps: mkdir "test\test-dotnet-new" -Force | Push-Location - - ps: dotnet new --lang fsharp + - ps: dotnet new console -lang f# - ps: dotnet restore - - ps: dotnet --verbose build - - ps: dotnet --verbose run a b + - ps: dotnet build + - ps: dotnet run a b - ps: Pop-Location diff --git a/docs/core/tools/media/using-ci-with-cli/screen1.png b/docs/core/tools/media/using-ci-with-cli/screen1.png new file mode 100644 index 0000000000000..aca119d7afcee Binary files /dev/null and b/docs/core/tools/media/using-ci-with-cli/screen1.png differ diff --git a/docs/core/tools/media/using-ci-with-cli/screen2.png b/docs/core/tools/media/using-ci-with-cli/screen2.png new file mode 100644 index 0000000000000..156bde52c8c0f Binary files /dev/null and b/docs/core/tools/media/using-ci-with-cli/screen2.png differ diff --git a/docs/core/tools/media/using-ci-with-cli/screen3.png b/docs/core/tools/media/using-ci-with-cli/screen3.png new file mode 100644 index 0000000000000..af9916e39b305 Binary files /dev/null and b/docs/core/tools/media/using-ci-with-cli/screen3.png differ diff --git a/docs/core/tools/media/using-ci-with-cli/screen4.png b/docs/core/tools/media/using-ci-with-cli/screen4.png new file mode 100644 index 0000000000000..2bc2241cd3e7e Binary files /dev/null and b/docs/core/tools/media/using-ci-with-cli/screen4.png differ diff --git a/docs/core/tools/using-ci-with-cli.md b/docs/core/tools/using-ci-with-cli.md index 9b0412629bb31..9928f3bbb2685 100644 --- a/docs/core/tools/using-ci-with-cli.md +++ b/docs/core/tools/using-ci-with-cli.md @@ -1,10 +1,10 @@ --- title: Using .NET Core SDK and tools in Continuous Integration (CI) | Microsoft Docs -description: Using .NET Core SDK and tools in Continuous Integration (CI) -keywords: .NET, .NET Core -author: blackdwarf +description: Information on the usage of the .NET Core SDK and its tools on the build server. +keywords: .NET, .NET Core, continuous integration, ci, build, automation, Travis CI, AppVeyor, Visual Studio Team Services, vsts +author: guardrex ms.author: mairaw -ms.date: 06/20/2016 +ms.date: 05/18/2017 ms.topic: article ms.prod: .net-core ms.technology: dotnet-cli @@ -15,93 +15,169 @@ ms.assetid: 0d6e1e34-277c-4aaf-9880-3ebf81023857 # Using .NET Core SDK and tools in Continuous Integration (CI) ## Overview -This document outlines the usage of .NET Core SDK and its tools on the build server. In general, on a CI build server, -you want to automate the installation in some way. The automation, ideally, should not require administrative -privileges if at all possible. -For SaaS CI solutions, there are several options. This document will cover two very popular ones, [TravisCI](https://travis-ci.org/) and -[AppVeyor](https://www.appveyor.com/). There are, of course, many other services out there, but the installation and -usage mechanisms should be similar. +This document outlines using the .NET Core SDK and its tools on a build server. 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. ## Installation options for CI build servers -## Using the native installers -If using installers that require administrative privileges is not something that presents a problem, native installers for -each platform can be used to set up the build server. This approach, especially in the case of Linux build servers, has -one advantage which is automatic installing of dependencies needed for the SDK to run. The native installers will also -install a system-wide version of the SDK, which may be desired; if it's not, you should look into the -[installer script usage](#using-the-installer-script) outlined below. +### Using the native installers -Using this approach is simple. For Linux, there is a choice of using a feed-based package manager, such as `apt-get` for -Ubuntu or `yum` for CentOS, or using the packages themselves (that is, DEB or RPM). The former would require setting up the -feed that contains the packages. +Native installers are available for macOS, Linux, and Windows. 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. Native installers also provide a system-wide installation of the SDK. -For Windows platforms, you can use the MSI. +macOS users should use the PKG installers. 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. On Windows, use the MSI installer. -All of the binaries can be found on the [.NET Core installation guide](https://aka.ms/dotnetcoregs) which points to the -latest stable releases. If you wish to use newer (and potentially unstable) releases or the latest, you can use the -links from the [CLI repo](https://github.com/dotnet/cli). +The latest stable binaries are found at [Get Started with .NET Core](https://aka.ms/dotnetcoregs). If you wish to use the latest (and potentially unstable) pre-release tooling, use the links provided at the [dotnet/cli GitHub repository](https://github.com/dotnet/cli#installers-and-binaries). 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. It also allows a very easy -automation. The script itself will download the ZIP/tarball files needed and will unpack them; it will also add the -install location on the local machine to the PATH so that the tools become available for invocation immediately -post-install. +### Using the installer script -The installer script can easily be automated at the start of the build to fetch and install the needed version of the SDK. -The "needed version" is whatever version application being built requires. You can choose the installation path so you -can install the SDK locally and then clean up after the build completes. This brings additional encapsulation and -atomicity to the build process. +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. 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. -The installation script reference can be found in the [dotnet-install](dotnet-install-script.md) document. +The installer script is automated to run at the start of the build to fetch and install the desired version of the SDK. The *desired version* is whatever version of the SDK your projects require to build. 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. The installation script reference is found in the [dotnet-install](dotnet-install-script.md) topic. -### Dealing with the dependencies -Using the installer script means that the native dependencies are not installed automatically and that you have to -install them if the operating system you are installing on already doesn't have them. You can see the list of prerequisites -in the [CLI repo](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md). +> [!NOTE] +> 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. See the list of prerequisites in the [.NET Core native prerequisites](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) topic. -## CI services setup examples -The below sections show examples of configurations using the mentioned CI SaaS offerings. +## CI setup examples -### TravisCI +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. The SaaS CI solutions covered are [Travis CI](https://travis-ci.org/), [AppVeyor](https://www.appveyor.com/), and [Visual Studio Team Services Build](https://www.visualstudio.com/docs/build/overview). -The [travis-ci](https://travis-ci.org/) can be configured to install the .NET Core SDK using the `csharp` language and the `dotnet` key. +### Manual setup -Just use: +Each SaaS service has its own methods for creating and configuring a build process. 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. -```yaml -dotnet: 1.0.0-preview2-003121 -``` +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. 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](#orchestrating-the-build) provides more detail on these options. -Travis can run both `osx` (OS X 10.11) and `linux` ( Ubuntu 14.04 ) job in a build matrix, see [example .travis.yml](https://github.com/dotnet/docs/blob/master/.travis.yml) -for more information. +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. Once you confirm that the script is running well locally, deploy it to your CI build server. A relatively simple PowerShell script demonstrates how to obtain the .NET Core SDK and install it on a Windows build server: -### AppVeyor +```powershell +$ErrorActionPreference="Stop" +$ProgressPreference="SilentlyContinue" -The [appveyor.com ci](https://www.appveyor.com/) has .NET Core SDK 1.0.1 already installed in the build worker image `Visual Studio 2017`. +# $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" -Just use: +# 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 -```yaml -os: Visual Studio 2017 +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://raw.githubusercontent.com/dotnet/cli/rel/1.0.1/scripts/obtain/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. For UNIX machines, the following bash script performs the actions described in the PowerShell script in a similar manner: + +```bash +#!/bin/bash +# Do not use an INSTALLDIR path containing spaces: +# https://github.com/dotnet/cli/issues/5281 +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://raw.githubusercontent.com/dotnet/cli/rel/1.0.1/scripts/obtain/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. ``` -It's possible to install a specific version of .NET Core SDK, see [example appveyor.yml](https://github.com/dotnet/docs/blob/master/appveyor.yml) -for more info. +### Travis CI -In the example, the .NET Core SDK binaries are downloaded, unzipped in a subdirectory and added to `PATH` env var. +You can configure [Travis CI](https://travis-ci.org/) to install the .NET Core SDK using the `csharp` language and the `dotnet` key. See the official Travis CI docs on [Building a C#, F#, or Visual Basic Project](https://docs.travis-ci.com/user/languages/csharp/) for more information. 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. -A build matrix can be added to run integration tests with multiple version of -the .NET Core SDK. +Travis CI runs both macOS (OS X 10.11, OS X 10.12) and Linux (Ubuntu 14.04) jobs in a *build matrix*, where you specify a combination of runtime, environment, and exclusions/inclusions to cover your build combinations for your app. See the [.travis.yml example](https://github.com/dotnet/docs/blob/master/.travis.yml) file and [Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) in the Travis CI docs for more information. 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. + +### AppVeyor + +[AppVeyor](https://www.appveyor.com/) installs the .NET Core 1.0.1 SDK with the `Visual Studio 2017` build worker image. Other build images with different versions of the .NET Core SDK are available; see the [appveyor.yml example](https://github.com/dotnet/docs/blob/master/appveyor.yml) and the [Build worker images](https://www.appveyor.com/docs/build-environment/#build-worker-images) topic in the AppVeyor docs for more information. + +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. Add a build matrix to run integration tests with multiple versions of the .NET Core SDK: ```yaml environment: matrix: - - CLI_VERSION: 1.0.0-preview2-003121 + - CLI_VERSION: 1.0.1 - CLI_VERSION: Latest install: - # .NET Core SDK binaries - - ps: $url = "https://dotnetcli.blob.core.windows.net/dotnet/preview/Binaries/$($env:CLI_VERSION)/dotnet-dev-win-x64.$($env:CLI_VERSION.ToLower()).zip" - # follow normal installation from binaries -``` \ No newline at end of file + # See appveyor.yml example for install script +``` + +### Visual Studio Team Services (VSTS) + +Configure Visual Studio Team Services (VSTS) to build .NET Core projects using one of these approaches: + +1. Run the script from the [manual setup step](#manual-setup) using your commands. +1. Create a build composed of several VSTS 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 topic only covers the manual option. For more information on composing a build with VSTS build tasks, visit the VSTS [Continuous integration and deployment](https://www.visualstudio.com/docs/build/overview) topic. + +To use a manual setup script in VSTS, create a new build definition and specify the script to run for the build step. This is accomplished using the VSTS 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. + + ![Selecting an empty build definition](./media/using-ci-with-cli/screen1.png) + +1. After configuring the repository to build, you're directed to the build definitions. Select **Add build step**: + + ![Adding a build step](./media/using-ci-with-cli/screen2.png) + +1. You're presented with the **Task catalog**. The catalog contains tasks that you use in the build. Since you have a script, select the **Add** button for **PowerShell: Run a PowerShell script**. + + ![Adding a PowerShell script step](./media/using-ci-with-cli/screen3.png) + +1. Configure the build step. Add the script from the repository that you're building: + + ![Specifying the PowerShell script to run](./media/using-ci-with-cli/screen4.png) + +## Orchestrating the build + +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 cannot be covered in a general way here. Explore the resources and samples provided in the documentation sets of [Travis CI](https://travis-ci.org/), [AppVeyor](https://www.appveyor.com/), and [VSTS](https://www.visualstudio.com/docs/build/overview) for more information on orchestrating your builds with each technology. + +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 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. 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 + +[Ubuntu acquisition steps](https://www.microsoft.com/net/core#linuxubuntu)