ドキュメント
circleci.com
Start Building for Free

Windows での Hello World

3 weeks ago2 min read
クラウド
Server v3.x
Server v2.x
On This Page

このドキュメントでは、CircleCI の Windows 実行環境で継続的インテグレーションを開始する方法を説明します。 今回初めて CircleCI をセットアップする場合は、先に 入門ガイドをご覧になることをお勧めします。

前提条件

作業を行う前に、以下を準備しておく必要があります。

Windows Executor の概要

Windows 実行環境 (executor) は、Universal Windows Platform (UWP) アプリケーションや .NET が実行可能な Windows 固有プロジェクト(.NET フレームワークなど) といった、Windows プロジェクトをビルドするためのツールを提供します。 Windows Executor の仕様と機能は以下のとおりです。

  • VM ベースでジョブの完全分離を保証
  • Windows Server 2019 Datacenter エディションとWindows Server 2022 Datacenter エディションの Server Core オプションのどちらでも使用可能
  • PowerShell がデフォルトのシェル (Bash と cmd を手動で選択可能)
  • Windows コンテナの実行に Docker Engine - Enterprise を使用可能

注:

  • メモ: Windows Executor は現時点で Windows コンテナのみをサポートしています。 現在、Windows で Linux コンテナを実行することはできません。
  • CircleCI Server v2.x では Orb の使用はサポートしていません(サーバー使用の場合は、 CircleCI Server での Windows Executor の使用を参照してください。)

Windows Executor イメージ

CircleCI は Windows Server 2019 では Visual Studio 2019 を、Windows Server 2022 では Visual Studio 2022 をサポートしています。 Windows イメージにプリインストールされているソフトフェアに関する情報は、 Developer Hub または Discuss フォーラムをご覧ください。 Developer Hub の Windows イメージのページには、最新のアップデートへのリンクが掲載されています。

Windows Server 2022 イメージに関する詳細は、 Discuss の投稿(英語) を参照してください。

Windows イメージは約 30 日ごとにアップデートされます。 Windows イメージの使用時にタグが指定されていない場合、デフォルトでは最新の安定バージョンが適用されます。 Windows のタグ付けスキームは以下のとおりです。

  • Current (Stable から変更) - 本番環境で使用可能な最新の Windows イメージを参照します。 このイメージは、安定性を適度に確保しつつ、ソフトウェアの定期アップデートを取り入れたいプロジェクトで使用してください。 アップデートは、通常月に 1 回の頻度で行われます。
  • Previous: 本番環境で使用可能な過去の Windows イメージを参照します。 このイメージは、最新のソフトウェアのアップデートに破壊的変更が含まれる場合などに使用できます。 アップデートは、通常月に 1 回の頻度で行われます。

  • Edge: 最新の Windows イメージを参照し、メインブランチの HEAD からビルドされます。 このタグは、最新の変更を含み完全な安定性が保証されていないテストバージョンのイメージとして使うことが想定されています。

サンプル設定ファイル

以下の設定スニペットを .circleci/config.yml ファイルに貼り付けると、CircleCI で Windows を使用できるようになります。

version: 2.1 # バージョン 2.1 を指定して Orb の使用を有効化します

orbs:
  win: circleci/windows@4.1 # The Windows orb give you everything you need to start using the Windows executor.

jobs:
  build: # name of your job
    executor:
      name: win/default # executor type
      size: "medium" # resource class, can be "medium", "large", "xlarge", "2xlarge", defaults to "medium" if not specified

    steps:
      # Commands are run in a Windows virtual machine environment
      - checkout
      - run: Write-Host 'Hello, Windows'

さらに、Orb を使わずに直接ジョブ内で Windows イメージにアクセスすることができます。

jobs:
  build-windows:
    machine:
      image: windows-server-2019:stable
      resource_class: windows.medium
      shell: powershell.exe -ExecutionPolicy Bypass

この場合、 Windows Orbを使用して設定を簡素化することを強く推奨します。

version: 2.1

orbs:
  win: circleci/windows@4.1

jobs:
  build:
    executor: win/server-2022
    steps:
      - run: Write-Host 'Hello, Windows'
workflows:
  my-workflow:
    jobs:
      - build

Windows Executor でのシェルの指定

Windows では 3 種類のシェルを使用してジョブステップを実行できます。

  • PowerShell (Windows Orb のデフォルト)
  • Bash
  • コマンド

シェルは、ジョブレベルまたはステップレベルで構成できます。 同じジョブ内で複数のシェルを使用可能です。 以下の例では、job 宣言と step 宣言に shell: 引数を追加して、Bash、PowerShell、およびコマンドを使用しています。

version: 2.1

orbs:
  win: circleci/windows@4.1

jobs:
  build:
    executor:
      name: win/default
    steps:
      # default shell is Powershell
      - run:
         command: $(echo hello | Out-Host; $?) -and $(echo world | Out-Host; $?)
         shell: powershell.exe
      - run:
         command: echo hello && echo world
         shell: bash.exe
      - run:
         command: echo hello & echo world
         shell: cmd.exe

注: 更新された、または他の Windows シェルツールをインストールすることも可能です。 たとえば、dotnet CLI により Powershell Core の最新版をインストールし、ジョブの連続するステップで使用することができます。


version: 2.1

orbs:
  win: circleci/windows@4.1

jobs:
  build:
    executor: win/default
    steps:
      - checkout
      - run: dotnet tool install --global PowerShell
      - run: pwsh ./<my-script>.ps1

Windows Executor での Windows Docker コンテナの実行

なお、Windows Dockerコンテナは、このように Windows Executor で実行することも可能です。

version: 2.1

orbs:
  win: circleci/windows@4.1

jobs:
  build:
    executor:
      name: win/default
      shell: powershell.exe
    steps:
      - checkout
      - run: systeminfo
      - run:
          name: "Check docker"
          shell: powershell.exe
          command: |
            docker info
            docker run hello-world:nanoserver-1809

サンプルアプリケーション

Windows Executor を使用した例として、少し進んだ (まだ初歩ですが) “hello world” を考えてみましょう。 この サンプルアプリケーションも「Hello World」をコンソールに出力します。そのために .NET コアを使用して実行可能ファイルを作成し、依存関係キャッシュを使用し、ビルドごとにアーティファクトを作成します。

注: CircleCI Server で Windows を使用している場合、 CircleCI Server での Windows Executor の使用 に記載されているように Orb の使用をマシンイメージに置き換えてください。

設定ファイルの全体は こちらで確認してください。 これにはブラウザーと UI のテストが含まれますが、ここでは hello-world のワークフローに注目します。

version: 2.1

上記のように、CircleCI のバージョン 2.1 を使用することを最初に宣言します。これにより、 Orb パイプラインを利用できます。

orbs:
  win: circleci/windows@2.4.0

次に、ビルドで使用する Orb を宣言します。 最初は Windows Orb のみを使用します。 このサンプルでは、2.4.0 バージョンの Orb を使用していますが、それ以降のバージョンも使用していただけます。

workflows:
  hello-world:
    jobs:
      - build

hello-world ワークフローを定義します。ここではbuild という単一のジョブを実行します。

jobs:
  build:
    executor:
      name: win/default

jobs キーの下に、buildジョブを定義し、使用する Orb により Executor を設定します。

    steps:
      - checkout

最初のステップでは、 checkout コマンドを実行して、バージョン管理システムからソース コードをプルします。

      - restore_cache:
          keys:
      - run:
          name: "プロジェクト依存関係のインストール"
          command: dotnet.exe restore
      - save_cache:
          paths:
            - C:\Users\circleci\.nuget\packages

次に設定ファイルでは、キャッシュを利用して、キャッシュされた依存関係を以前のビルドから復元します。 dotnet restore コマンドは、まだインストールされていない、または復元されていないすべての依存関係をキャッシュからフェッチします。 キャッシュの詳細については、 キャッシュに関するドキュメントを参照してください。

      - run:
          name: "ビルド ステップの実行"
          command: dotnet.exe publish -c Release -r win10-x64
      - run:
          name: "実行可能ファイルのテスト"
          command: .\bin\Release\netcoreapp2.1\win10-x64\publish\circleci-demo-windows.exe

続いて 2 つのステップを実行します。1 つは Windows 10 用の実行可能ファイルをビルドし、もう 1 つはその実行可能ファイルをテストします (コンソールに「Hello World」と出力されます)。

      - store_artifacts:
          path: .\bin\Release\netcoreapp2.1\win10-x64\publish\circleci-demo-windows.exe

最後のステップでは、ビルド実行可能ファイルをアーティファクトとして保存し、CircleCI Web アプリケーションまたは API からアクセスできるようにします。

ビルドへの SSH 接続

Windows ビルド コンテナに SSH 接続することができます。 これは、パイプラインに関する問題のトラブルシューティングに便利です。 Windows コンテナに SSH 接続するには、以下の手順を実行します。

手順

  1. SSH キーを GitHub アカウントまたは Bitbucket アカウントに追加していることを確認します。

  2. SSH 接続を有効にしてジョブを起動するには、[Rerun Workflow (ワークフローを再実行する)] ドロップダウン メニューから [Rerun job with SSH (SSH でジョブを再実行する)] オプションを選択します。

  3. SSH から Windows ジョブに接続し、bash シェルを使用すると、ターミナルのプロンプトが空になってしまうSSH 接続の詳細情報

SSH 接続するときには、実行するシェルの名前を渡してください。 上のビルドで cmd.exe を実行するには、ssh -p <remote_ip> -- cmd.exe を実行します。

以下のオプションが利用できます。

  • powershell.exe
  • bash.exe
  • cmd.exe

ビルドで SSH を使用する方法については、 こちらを参照してください。

既知の問題

Windows Executor には以下に挙げる問題が確認されており、可能な限り早期の対処を目指しています。

  • SSH から Windows ジョブに接続し、bash シェルを使用すると、ターミナルのプロンプトが空になってしまう
  • 現時点では、ネストされた仮想化をサポートしていません (--platform linux フラグの使用など)。

CircleCI Server での Windows Executor の使用

CircleCI Server Windows イメージに含まれている内容の詳細はシステム管理者に問い合わせるか、 Discuss フォーラムのページをご覧ください。

シェルの指定

dotnet CLI を使って Powershell Core をインストールします。

Windows Docker コンテナの実行

次のステップ

CircleCI の機能については、以下のドキュメントを確認してください。


ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。