Cookiecutter 拡張機能の使用

Cookiecutter は、テンプレートの検出、テンプレート オプションの入力、プロジェクトとファイルの作成を行うためのグラフィカル ユーザー インターフェイスを提供します。 Visual Studio 2017 以降には、Cookiecutter 拡張機能が含まれています。 この機能は、以前のバージョンの Visual Studio に個別にインストールできます。

Visual Studio では、[表示]>[Cookiecutter Explorer] から Cookiecutter 拡張機能を利用できます。

Visual Studio 内の Cookiecutter エクスプローラーのメイン ウィンドウを示すスクリーンショット。

前提条件

  • 見ることができます。 製品をインストールするには、「Visual Studio のインストール」の手順に従います。

  • Python 3.3 以降 (32 または 64 ビット)、または Anaconda 3 4.2 以降 (32 または 64 ビット)。

    • 適切な Python インタープリターを使用できない場合、警告が Visual Studio に表示されます。

    • Visual Studio の実行中に Python インタープリターをインストールした場合は、[Cookiecutter Explorer] ツールバーの [ホーム] オプションを選択すると、新しくインストールしたインタープリターが検出されます。 詳細については、「Visual Studio での Python 環境の作成と管理」を参照してください

Cookiecutter Explorer を操作する

[Cookiecutter Explorer] では、テンプレートの参照と選択、ローカル コンピューターへのテンプレートの複製、テンプレート オプションの設定、テンプレートからのコードの作成を行うことができます。

テンプレートの参照

[Cookiecutter Explorer] でテンプレートを参照して、既にインストールされているテンプレートと利用可能なテンプレートを確認できます。

  1. [Cookiecutter Explorer] で、ツール バーの [ホーム] オプションを選択して、使用可能なテンプレートを表示します。

    おすすめおよび GitHub カテゴリのテンプレートのリストと、Visual Studio 内の Cookiecutter エクスプローラーのホーム ページを示すスクリーンショット。

    ホーム ページにテンプレートの一覧が以下の 4 つのグループに分けて表示され、一覧からテンプレートを選択できます。

    グループ 説明 メモ
    インストール済み ローカル コンピューターにインストールされたテンプレート。 オンライン テンプレートが使用されると、そのリポジトリが ~/.cookiecutters のサブフォルダーに自動的に複製されます。 [Cookiecutter Explorer] ツール バーの [削除] を選択すると、インストールされているテンプレートをシステムから削除できます。
    推奨 推奨フィードから読み込まれたテンプレートです。 Microsoft が既定のフィードを選別します。 [Set Cookiecutter options] (Cookiecutter のオプションの設定)」の手順に従って、フィードをカスタマイズできます。
    GitHub キーワード "cookiecutter" での GitHub の検索結果。 git リポジトリの一覧は、ページ分割された形式で返されます。 結果の一覧が現在のビューを超えている場合は、[さらに読み込む] オプションを選択して、ページ分割された結果の次のセットを一覧に表示できます。
    カスタム Cookiecutter Explorer を通じて定義されたカスタム テンプレート。 カスタム テンプレートの場所を Cookiecutter Explorer の検索ボックスに入力すると、その場所がこのグループに表示されます。 カスタム テンプレートは、git リポジトリへの完全なパス、またはローカル ディスク上のフォルダへの完全なパスを入力して定義できます。
  2. 特定のカテゴリに使用可能なテンプレートの一覧を表示または非表示にするには、カテゴリの横にある矢印を選択します。

テンプレートの複製

Cookiecutter Explorer で使用可能なテンプレートを操作して、使用するローカル コピーを作成できます。

  1. Cookiecutter Explorer で、テンプレートを選択します。 選択したテンプレートに関する情報が、Cookiecutter Explorer ホーム ページの下部に表示されます。

    Visual Studio の Cookiecutter エクスプローラーで複製するテンプレートの選択方法を示すスクリーンショット。

    テンプレートの概要には、テンプレートの詳細情報へのリンクが含まれています。 テンプレートに関する GitHub リポジトリ ページに移動し、テンプレート Wiki を表示したり、報告された問題を見つけたりすることができます。

  2. 選択したテンプレートを複製するには、[次へ] を選択します。 テンプレートのローカル コピーが作成されます。

複製の動作は、選択したテンプレートの種類によって異なります。

テンプレートの種類 Behavior
インストール済み 選択したテンプレートが Visual Studio の以前のセッションでインストールされていた場合、そのテンプレートは自動的に削除され、最新バージョンがローカル コンピューターにインストールされ、それが複製されます。
推奨 選択したテンプレートが複製され、ローカル コンピューターにインストールされます。
GitHub 選択したテンプレートが複製され、ローカル コンピューターにインストールされます。
カスタム検索 - URL: git リポジトリのカスタム URL をCookiecutter Explorer の検索ボックスに入力し、テンプレートを選択した場合、選択したテンプレートが複製され、ローカル コンピューターにインストールされます。
- フォルダー パス: 検索ボックスにカスタム フォルダーのパスを入力し、テンプレートを選択した場合、そのテンプレートが複製されずに Visual Studio に読み込まれます。

重要

Cookiecutter のテンプレートは ~/.cookiecutters という単一のフォルダーの下に複製されます。 各サブフォルダーの名前は git リポジトリの名前に従って付けられ、GitHub のユーザー名を含みません。 作成者が異なる、同じ名前の複数のテンプレートを複製すると、競合が発生する可能性があります。 その場合、Cookiecutter では、同じ名前の別のテンプレートで既存のテンプレートを上書きすることはできません。 他のテンプレートをインストールするには、先に既存のテンプレートを削除する必要があります。

テンプレート オプションの設定

テンプレートをローカルにインストールして複製すると、[オプション] ページが表示されます。 このページで、生成されたファイルのフォルダー パスの場所などの設定を指定できます。

Visual Studio の Cookiecutter エクスプローラーに新しくインストールおよび複製されたテンプレートのオプションを示すスクリーンショット。

各 Cookiecutter テンプレートは、それぞれ独自のオプション セットを定義します。 設定に既定値を使用できる場合、[オプション] ページの対応するフィールドに推奨されるテキストが表示されます。 既定値はコード スニペットの場合もあります。これは主に、他のオプションを使用する動的な値であるときです。

この例では、テンプレート名は cookiecutter-flask/cookiecutter-flask として定義されています。 設定値を変更できるときは、フィールド テキストを編集できます。

  1. [作成先] フィールドに、Cookiecutter によって生成されるファイルのフォルダー パスの場所を入力します。

  2. 次に、テンプレートに必要な以下のようなその他のオプションを設定します。

    • full_name: テンプレートに適用する完全な名前。
    • email: テンプレート作成者のメール アドレス。
    • github_username: テンプレート作成者の GitHub エイリアス。
    • python_version: テンプレートから作成された Web アプリのターゲットの Python バージョン。

構成ファイルで既定値を設定する

ユーザー構成ファイルを使用して、特定のオプションの既定値をカスタマイズできます。 Cookiecutter 拡張機能はユーザー構成ファイルを検出すると、テンプレートの既定値を構成ファイルの既定値で上書きします。 この動作の詳細については、Cookiecutter ドキュメントの「ユーザー構成」セクションを参照してください。

指定したタスクをオプトアウトする

一部のテンプレートは、コード生成後に実行する特定の Visual Studio タスクを識別します。 一般的なタスクには、Web ブラウザーを開く、エディターでファイルを開く、依存関係をインストールするなどがあります。 テンプレートが特定のタスクを識別すると、[完了時に追加タスクを実行] 設定がオプションの一覧に追加されます。 この設定を構成して、指定した Visual Studio タスクをオプトアウトできます。

テンプレートからコードを作成する

テンプレート オプションを設定したら、Cookiecutter でプロジェクト ファイルを作成し、コードを生成する準備が整います。

ダイアログには、オプションの一覧の後にボタンが表示されます。 ボタンのテキストはテンプレートによって異なります。 [Create and Open folder] (フォルダーを作成して開く)[ソリューションに追加] などが表示されます。

  1. [オプション] ページで、[Create and Open folder] (フォルダーを作成して開く)[ソリューションに追加] など、オプションの一覧に続くボタンを選択します。

    テンプレート オプションのリスト末尾にある [フォルダーを作成して開く] ボタンを示すスクリーンショット。

    Cookiecutter によってコードが生成されます。 出力フォルダーが空でない場合は、警告が表示されます。

    • テンプレートの出力についてよく知っていて、ファイルを上書きしても問題ない場合は、[OK] を選択して警告を無視します。

    • そうでない場合は、[キャンセル] を選択し、空のフォルダーを指定して、作成されたファイルを空でない出力フォルダーに手動でコピーします。

  2. Cookiecutter によってファイルが正常に作成されると、Visual Studio によってソリューション エクスプローラーでテンプレート プロジェクト ファイルが開かれます。

Cookiecutter のオプションを設定する

Cookiecutter のオプションは、[ツール]>[オプション]>[Cookiecutter] から表示できます。

Visual Studio の Cookiecutter のオプションを示すスクリーンショット。

オプション 説明
更新されたテンプレートを確認する Cookiecutter が、インストールされているテンプレートの更新をオンラインで自動的に確認するかどうかを制御します。
推奨されるフィード URL 推奨されるテンプレート フィード ファイルの場所です。 場所は、URL またはローカル ファイルへのパスで指定されます。 マイクロソフトによって選別された既定のフィードを使用する場合は、URL を空のままにします。 フィードでは、改行で区切られたテンプレートの場所の単純なリストが提供されます。 選別されたフィードの変更を要求するには、GitHub 上のソースに対して pull request を行います。
ヘルプの表示 Cookiecutter ウィンドウの上部にヘルプ情報のバーを表示するかどうかを指定します。

Visual Studio 向けの Cookiecutter テンプレートの最適化

Visual Studio の Cookiecutter 拡張機能は、Cookiecutter v1.4 用に作成されたテンプレートをサポートします。 Cookiecutter テンプレートの作成の詳細については、Cookiecutter ドキュメントを参照してください。

テンプレート変数の既定のレンダリングは、データの型 (文字列またはリスト) によって異なります。

  • String: String データ型では、変数名のラベル、値入力用のテキスト ボックス、および既定値を示す基準値が使用されます。 テキスト ボックスのツールヒントに既定値が表示されます。
  • List: List データ型では、変数名のラベルと、値選択用のコンボ ボックスが使用されます。 コンボ ボックスのツールヒントに既定値が表示されます。

このレンダリングは、Visual Studio に固有の (Cookiecutter CLI には無視される) cookiecutter.json ファイルで他のメタデータを指定することによって改善できます。 すべてのプロパティは省略可能です。

プロパティ 説明
label エディターの上部に、変数名の代わりに変数に関して表示されるテキストを指定します。
description エディット コントロールに、変数の既定値の代わりに表示するツールヒントを指定します。
url ラベルをハイパーリンクに変更し、URL を示すツールヒントと共に表示します。 ハイパーリンクを選択すると、ユーザーの既定のブラウザーでその URL が開きます。
selector 変数のエディターをカスタマイズできます。 現在、以下のセレクターがサポートされています。
- string: 標準のテキスト ボックス (文字列の既定値)。
- list: 標準のコンボ ボックス (リストの既定値)。
- yesno: yn のいずれかを選択するコンボ ボックス (文字列用)。
- odbcConnection: データベース接続ダイアログを開く楕円形のボタン (...) があるテキスト ボックス。

以下の例に、レンダリング プロパティを設定する方法を示します。

{
    "site_name": "web-app",
    "python_version": ["3.5.2"],
    "use_azure": "y",

    "_visual_studio": {
        "site_name": {
            "label": "Site name",
            "description": "E.g. <site-name>.azurewebsites.net (can only contain alphanumeric characters and `-`)"
        },
        "python_version": {
            "label": "Python version",
            "description": "The version of Python to run the site on"
        },
        "use_azure" : {
            "label": "Use Azure",
            "description": "Include Azure deployment files",
            "selector": "yesno",
            "url": "https://azure.microsoft.com"
        }
    }
}

Visual Studio タスクの実行

Cookiecutter には、ファイルの生成後に任意の Python コードを実行できる Post-Generate Hooks (生成後フック) と呼ばれる機能があります。 この機能は柔軟ですが、Visual Studio への簡単なアクセスを許可しません。

この機能を使用して、Visual Studio エディターまたはその Web ブラウザーでファイルを開くことができます。 仮想環境を作成し、パッケージの要件をインストールするようにユーザーに求める Visual Studio UI をトリガーすることもできます。

これらのシナリオを許可するために、Visual Studio は cookiecutter.json ファイルで拡張メタデータを検索します。 ユーザーが生成されたファイルをソリューション エクスプローラーで開いた後、またはファイルが既存のプロジェクトに追加された後に実行するコマンドを検索します。 (前述したように、ユーザーはテンプレート オプション [Run additional tasks on completion] (完了時に追加タスクを実行) をオフにすることでタスクの実行をオプトアウトできます)。

次の例に、cookiecutter.json ファイルで拡張メタデータを設定する方法を示します。

"_visual_studio_post_cmds": [
    {
        "name": "File.OpenFile",
        "args": "{{cookiecutter._output_folder_path}}\\readme.txt"
    },
    {
        "name": "Cookiecutter.ExternalWebBrowser",
        "args": "https://video2.skills-academy.com"
    },
    {
        "name": "Python.InstallProjectRequirements",
        "args": "{{cookiecutter._output_folder_path}}\\dev-requirements.txt"
    }
]

コマンドを名前で指定し、Visual Studio のローカライズされたインストールで動作するように、ローカライズされていない (英語の) 名前を使用する必要があります。 Visual Studio のコマンド ウィンドウで、コマンド名のテストと検索を行うことができます。

1 つの引数を渡す場合は、前の例のメタデータ name に示したように、引数を文字列として指定します。

引数を渡す必要がない場合は、値を空の文字列のままにするか、JSON ファイルから省略します。

"_visual_studio_post_cmds": [
    {
        "name": "View.WebBrowser"
    }
]

複数の引数の場合は、配列を使用します。 スイッチの場合は、この例に示すように、正しく引用されるようにスイッチとその値を別の引数に分けます。

"_visual_studio_post_cmds": [
    {
        "name": "File.OpenFile",
        "args": [
            "{{cookiecutter._output_folder_path}}\\read me.txt",
            "/e:",
            "Source Code (text) Editor"
        ]
    }
]

引数は他の Cookiecutter 変数を参照できます。 前の例では、ファイルを生成する絶対パスの作成に内部変数 _output_folder_path が使用されています。

Python.InstallProjectRequirements コマンドは、既存のプロジェクトにファイルを追加する際にのみ機能します。 ソリューション エクスプローラーの Python プロジェクトによって処理されますが、ソリューション エクスプローラー - フォルダー ビューの表示中はメッセージを受け取るプロジェクトがないため、この制限が存在します。

テンプレートの問題のトラブルシューティング

Cookiecutter の操作時の Python 環境とコードのトラブルシューティングに関するヒントについては、以降のセクションを参照してください。

テンプレートの読み込みエラー

一部のテンプレートでは、cookiecutter.json ファイル内で boolean 型などの無効なデータ型が使用されている場合があります。 このような例は、[テンプレート情報] ウィンドウの [問題] リンクを選択してテンプレート作成者に報告することができます。

フック スクリプトの失敗

一部のテンプレートで、Cookiecutter UI と互換性のない生成後スクリプトが使用されている場合があります。 たとえば、ユーザーに入力をクエリするスクリプトは、端末コンソールがないため失敗することがあります。

Windows でサポートされていないフック スクリプト

事後スクリプト ファイルが .sh の場合、Windows コンピューター上のアプリケーションとの関連付けができない場合があります。 互換性のあるアプリケーションを Windows ストアで見つけるように求める Windows ダイアログが表示されることがあります。

既知の問題があるテンプレート

Cookiecutter Explorer で、テンプレートの概要の [問題] リンクを使用して、テンプレートに既知の問題があるかどうかを確認できます。

Cookiecutter エクスプローラーでテンプレートの既知の問題に関するリストを開く方法を示すスクリーンショット。

このリンクをクリックすると、テンプレートの GitHub 問題のページが開きます。

GitHub でレポートされたテンプレートに関する問題のリストを示すスクリーンショット。