Cookiecutter 拡張機能の使用

Cookiecutter は、テンプレートの検出、テンプレート オプションの入力、プロジェクトとファイルの作成を行うためのグラフィカル ユーザー インターフェイスを提供します。 Cookiecutter は Visual Studio 2017 に付属しており、Visual Studio の以前のバージョンにも個別にインストールできます。

Cookiecutter には、Python 3.3 以降 (32 または 64 ビット) または Anaconda 3 4.2 以降 (32 または 64 ビット) が必要です。 適切な Python インタープリターを使用できない場合、警告が Visual Studio に表示されます。 Visual Studio の実行中に Python インタープリターをインストールした場合は、Cookiecutter ツールバーの [ホーム] ボタンをクリックすると新しくインストールしたインタープリターが検出されます。

インストールしたら、[表示] > [Cookicutter Explorer (Cookiecutter エクスプローラー)] を選択して Cookiecutter のウィンドウを開きます。

Cookiecutter のメイン ウィンドウ

Cookiecutter のワークフロー

Cookiecutter の操作は、テンプレートを参照して選択し、ローカル コンピューターに複製し、オプションを設定して、そのテンプレートからコードを作成するというプロセスです。以下のセクションで、このプロセスについて説明します。

テンプレートの参照

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

グループ化 説明
インストール済み ローカル コンピューターにインストール済みのテンプレートです。 オンライン テンプレートが使用されると、そのリポジトリが ~/.cookiecutters のサブフォルダーに自動的に複製されます。 インストール済みテンプレートを選択して Del キーを押すと削除できます。
推奨 推奨フィードから読み込まれたテンプレートです。 既定のフィードはマイクロソフトによって選別されます。 フィードをカスタマイズする方法の詳細については、後の「Cookiecutter のオプション」をご覧ください。
GitHub Cookiecutter キーワードの GitHub での検索結果です。 GitHub からの結果は改ページ調整されて返されます。さらに多くの結果がある場合は、一覧の最後に [さらに読み込む] が表示されます。
カスタム カスタムの場所が検索ボックスに入力されると、このグループに表示されます。 GitHub リポジトリへの完全なパスを入力するか、ローカル ディスク上のフォルダーへの完全なパスを入力します。

複製

テンプレートを選択して [次へ] を選択すると、Cookiecutter によって作業用のローカル コピーが作成されます。

[推奨] または [GitHub] グループからテンプレートを選択するか、検索ボックスにカスタム URL を入力してそのテンプレートを選択した場合は、テンプレートが複製されてローカル コンピューターにインストールされます。 そのテンプレートが Visual Studio の以前のセッションでインストールされている場合は、自動的に削除され、最新のバージョンが複製されます。

[インストール済み] グループからテンプレートを選択するか、検索ボックスにカスタム フォルダーのパスを入力してそのテンプレートを選択した場合は、テンプレートが複製されずに Visual Studio に読み込まれます。

重要

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

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

テンプレートがローカルにインストールされると、Cookiecutter のオプション ページが表示され、Cookiecutter のファイルを生成する場所やその他のオプションを指定できます。

Cookiecutter のオプション ページ

各 Cookiecutter テンプレートでは、独自のオプションのセットを定義し、各オプションの既定値 (各エントリ フィールドで推奨テキストとして表示される値) を指定します。 既定値はコード スニペットの場合もあります。これは主に、他のオプションを使用する動的な値である場合です。

各オプションの既定値はユーザー構成ファイルを使用してカスタマイズできます。 Cookiecutter 拡張機能はユーザー構成ファイルを検出すると、テンプレートの既定値をユーザー構成ファイルの既定値で上書きします。 これについては、Cookiecutter ドキュメントの User Config に関するセクションで説明しています。

テンプレートでコード生成後に特定の Visual Studio タスクを実行するように指定した場合は、[Run additional tasks on completion (完了時に追加タスクを実行)] オプションが表示されます。このオプションで、それらのタスクを実行しないように選択することもできます。 最も一般的なタスクの使用方法としては、Web ブラウザーを開く、エディターでファイルを開く、依存関係をインストールするなどがあります。

作成

オプションの設定が完了したら、[作成] を選択してコードを生成します。 出力フォルダーが空でない場合は、警告が表示されます。 テンプレートの出力に慣れていてファイルを上書きしても問題ない場合は、警告を無視してかまいません。 それ以外の場合は、[キャンセル] を選択し、空のフォルダーを指定して、作成したファイルを空でない出力フォルダーに手動でコピーします。

ファイルが正常に作成されると、ファイルをソリューション エクスプローラーで開くためのオプションが Cookiecutter に表示されます。

ソリューション エクスプローラーのコマンドが表示された Cookiecutter

Cookiecutter のオプション

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

Cookiecutter のオプション

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

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

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

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

  • 文字列: 変数名のラベル、値を入力するためのテキスト ボックス、既定値を表示するウォーターマーク。 テキスト ボックスのツールヒントには既定値が表示されます。
  • リスト: 変数名のラベル、値を選択するためのコンボ ボックス。 コンボ ボックスのツールヒントには既定値が表示されます。

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

プロパティ 説明
group1 エディターの上部に、変数名の代わりに変数に対して表示される内容を指定します。
説明 編集コントロールに、変数の既定値の代わりに説明として表示されるツールヒントを指定します。
URL ラベルをハイパーリンクに変更し、URL を示したツールヒントとともに表示します。 ハイパーリンクをクリックすると、ユーザーの既定のブラウザーでその URL が開きます。
[セレクター] 変数のエディターをカスタマイズできます。 現在、次のセレクターがサポートされています。
  • string: 標準のテキスト ボックス (文字列の既定値)。
  • list: 標準のコンボ ボックス (リストの既定値)。
  • yesno: yn のいずれかを選択するコンボ ボックス (文字列用)。
  • odbcConnection: データベース接続ダイアログを起動する "..." ボタンのあるテキスト ボックス。

例:

{
    "site_name": "web-app",
    "python_version": ["3.5.2", "2.7.12"],
    "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 (完了時に追加タスクを実行)] をオフにすることでタスクを実行しないよう選択できます)。

例:

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

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

1 つの引数を渡す場合は、前の例のように文字列として指定します。

引数を渡す必要がない場合は、空の文字列のままにするか、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.json 内で、ブール型などの無効なデータ型が使用されている場合があります。 これはテンプレートの作成者に報告する必要があります。 テンプレート情報ウィンドウにある [問題] リンクをクリックしてください。

フック スクリプトの失敗

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

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

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

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

複製エラー

  • wildfish/cookiecutter-django-crud (サブフォルダー名に無効な文字 | が含まれている)
  • cookiecutter-pyvanguard (サブフォルダー名に無効な文字 | が含まれている)

読み込みエラー

  • chrisdev/wagtail-cookiecutter-foundation (cookiecutter.json でブール型を使用している)
  • quintoandar/cookiecutter-android (テンプレート フォルダーが存在しない)

実行エラー

  • iknite/cookiecutter-ansible-role (事後フック スクリプトにコンソール入力が必要)
  • benregn/cookiecutter-django-ansible (jinja エラー)

バッシュの使用 (致命的ではない)

  • openstack-dev/cookiecutter