Cookiecutter 拡張機能の使用

[アーティクル]
04/18/2024

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

Visual Studio では、[表示]>[Cookiecutter Explorer] から 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] でテンプレートを参照して、既にインストールされているテンプレートと利用可能なテンプレートを確認できます。

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

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

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

特定のカテゴリに使用可能なテンプレートの一覧を表示または非表示にするには、カテゴリの横にある矢印を選択します。

テンプレートの複製

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

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

テンプレートの概要には、テンプレートの詳細情報へのリンクが含まれています。テンプレートに関する GitHub リポジトリページに移動し、テンプレート Wiki を表示したり、報告された問題を見つけたりすることができます。
選択したテンプレートを複製するには、[次へ] を選択します。テンプレートのローカルコピーが作成されます。

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

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

重要

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

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

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

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

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

[作成先] フィールドに、Cookiecutter によって生成されるファイルのフォルダーパスの場所を入力します。
次に、テンプレートに必要な以下のようなその他のオプションを設定します。
- full_name: テンプレートに適用する完全な名前。
- email: テンプレート作成者のメールアドレス。
- github_username: テンプレート作成者の GitHub エイリアス。
- python_version: テンプレートから作成された Web アプリのターゲットの Python バージョン。

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

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

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

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

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

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

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

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

Cookiecutter によってコードが生成されます。出力フォルダーが空でない場合は、警告が表示されます。
- テンプレートの出力についてよく知っていて、ファイルを上書きしても問題ない場合は、[OK] を選択して警告を無視します。
- そうでない場合は、[キャンセル] を選択し、空のフォルダーを指定して、作成されたファイルを空でない出力フォルダーに手動でコピーします。
Cookiecutter によってファイルが正常に作成されると、Visual Studio によってソリューションエクスプローラーでテンプレートプロジェクトファイルが開かれます。

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

Cookiecutter のオプションは、[ツール]>[オプション]>[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`: `y` と `n` のいずれかを選択するコンボボックス (文字列用)。 - `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://learn.microsoft.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 問題のページが開きます。

次の方法で共有

Cookiecutter 拡張機能の使用

前提条件

Cookiecutter Explorer を操作する

テンプレートの参照

テンプレートの複製

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

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

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

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

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

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

Visual Studio タスクの実行

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

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

フックスクリプトの失敗

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

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

フィードバック

その他のリソース

次の方法で共有

Cookiecutter 拡張機能の使用

前提条件

Cookiecutter Explorer を操作する

テンプレートの参照

テンプレートの複製

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

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

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

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

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

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

Visual Studio タスクの実行

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

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

フック スクリプトの失敗

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

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

関連するコンテンツ

フィードバック

その他のリソース

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

フックスクリプトの失敗

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