Cookiecutter 拡張機能の使用Using the Cookiecutter Extension

Cookiecutter は、テンプレートの検出、テンプレート オプションの入力、プロジェクトとファイルの作成を行うためのグラフィカル ユーザー インターフェイスを提供します。Cookiecutter provides a graphical user interface to discover templates, input template options, and create projects and files. Cookiecutter は Visual Studio 2017 に付属しており、Visual Studio の以前のバージョンにも個別にインストールできます。It's included with Visual Studio 2017 and can be installed separately in earlier versions of Visual Studio.

Cookiecutter には、Python 3.3 以降 (32 ビットまたは 64 ビット) または Anaconda 3 4.2 以降 (32 ビットまたは 64 ビット) が必要です。Cookiecutter requires Python 3.3 or later (32-bit or 64-bit) or Anaconda 3 4.2 or later (32-bit or 64-bit). 適切な Python インタープリターを使用できない場合、警告が Visual Studio に表示されます。If a suitable Python interpreter isn't available, Visual Studio displays a warning. Visual Studio の実行中に Python インタープリターをインストールした場合は、Cookiecutter ツールバーの [ホーム] ボタンをクリックすると新しくインストールしたインタープリターが検出されます。If you install a Python interpreter while Visual Studio is running, click the Home button on the Cookiecutter toolbar to detect the newly installed interpreter.

インストールしたら、[表示] > [Cookiecutter Explorer] を選択して Cookiecutter のウィンドウを開きます。Once installed, select View > Cookiecutter Explorer to open its window:

Cookiecutter のメイン ウィンドウ

Cookiecutter のワークフローCookiecutter workflow

Cookiecutter の操作は、テンプレートを参照して選択し、ローカル コンピューターに複製し、オプションを設定して、そのテンプレートからコードを作成するというプロセスです。以下のセクションで、このプロセスについて説明します。Working with Cookiecutter is a process of browsing and selecting a template, cloning it to your local machine, setting options, then creating code from that template, as described in the sections that follow.

テンプレートの参照Browsing templates

Cookiecutter のホーム ページにはテンプレートの一覧が次のグループに分けて表示され、一覧からテンプレートを選択できます。The Cookiecutter home page displays a list of templates to choose from, organized into the following groups:

グループ化Group 説明Description
インストール済みInstalled ローカル コンピューターにインストール済みのテンプレートです。Templates that have been installed to your local machine. オンライン テンプレートが使用されると、そのリポジトリが ~/.cookiecutters のサブフォルダーに自動的に複製されます。When an online template is used, its repository is automatically cloned to a subfolder of ~/.cookiecutters. インストール済みテンプレートを選択して Del キーを押すと削除できます。You can delete a selected installed template by pressing Del.
推奨Recommended 推奨フィードから読み込まれたテンプレートです。Templates loaded from the recommended feed. 既定のフィードはマイクロソフトによって選別されます。The default feed is curated by Microsoft. フィードをカスタマイズする方法の詳細については、後の「Cookiecutter のオプション」をご覧ください。See Cookiecutter options below for details on customizing the feed.
GitHubGitHub Cookiecutter キーワードの GitHub での検索結果です。GitHub search results for the cookiecutter keyword. GitHub からの結果は改ページ調整されて返されます。さらに多くの結果がある場合は、一覧の最後に [さらに読み込む] が表示されます。Results from GitHub come back paginated, if more results are available, Load More appears at the end of the list.
カスタムCustom カスタムの場所が検索ボックスに入力されると、このグループに表示されます。When a custom location is entered in the search box, it appears in this group. GitHub リポジトリへの完全なパスを入力するか、ローカル ディスク上のフォルダーへの完全なパスを入力します。You can either type in a full path to the GitHub repository, or the full path to a folder on your local disk.

複製Cloning

テンプレートを選択して [次へ] を選択すると、Cookiecutter によって作業用のローカル コピーが作成されます。When you select a template followed by Next, Cookiecutter makes a local copy to work from.

[推奨] または [GitHub] グループからテンプレートを選択するか、検索ボックスにカスタム URL を入力してそのテンプレートを選択した場合は、テンプレートが複製されてローカル コンピューターにインストールされます。If you select a template from the Recommended or GitHub groups, or enter a custom URL into the search box and select that template, it's cloned and installed on your local machine. そのテンプレートが Visual Studio の以前のセッションでインストールされている場合は、自動的に削除され、最新のバージョンが複製されます。If that template was installed in a previous session of Visual Studio, it's automatically deleted and the latest version is cloned.

[インストール済み] グループからテンプレートを選択するか、検索ボックスにカスタム フォルダーのパスを入力してそのテンプレートを選択した場合は、テンプレートが複製されずに Visual Studio に読み込まれます。If you select a template from the Installed group, or enter a custom folder path into the search box and select that template, Visual Studio loads that template without cloning.

重要

Cookiecutter のテンプレートは ~/.cookiecutters という単一のフォルダーの下に複製されます。Cookiecutter templates are cloned under a single folder ~/.cookiecutters. 各サブフォルダーの名前は git リポジトリの名前に従って付けられ、GitHub のユーザー名を含みません。Each subfolder is named after the git repository name, which does not include the GitHub user name. 作成者が異なる、同じ名前の複数のテンプレートを複製すると、競合が発生する可能性があります。Conflicts can arise if you clone different templates with the same name that come from different authors. その場合、Cookiecutter では、同じ名前の別のテンプレートで既存のテンプレートを上書きすることはできません。In this case, Cookiecutter prevents you from overwriting the existing template with a different template of the same name. 他のテンプレートをインストールするには、先に既存のテンプレートを削除する必要があります。To install the other template, you must first delete the existing one.

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

テンプレートがローカルにインストールされると、Cookiecutter のオプション ページが表示され、Cookiecutter のファイルを生成する場所やその他のオプションを指定できます。After the template is installed locally, Cookiecutter displays an options page where you can specify where you want Cookiecutter to generate files along with other options:

Cookiecutter のオプション ページ

各 Cookiecutter テンプレートでは、独自のオプションのセットを定義し、各オプションの既定値 (各エントリ フィールドで推奨テキストとして表示される値) を指定します。Each Cookiecutter template defines its own set of options, and specifies a default value for each one (displayed as the suggested text in each entry field). 既定値はコード スニペットの場合もあります。これは主に、他のオプションを使用する動的な値である場合です。A default value may be a code snippet, often when it's a dynamic value that uses other options.

各オプションの既定値はユーザー構成ファイルを使用してカスタマイズできます。It's possible to customize default values for specific options with a user configuration file. Cookiecutter 拡張機能はユーザー構成ファイルを検出すると、テンプレートの既定値をユーザー構成ファイルの既定値で上書きします。When the Cookiecutter extension detects a user configuration file, it overwrites the template's default values with the user config's default values. この動作については、Cookiecutter ドキュメントの User Config に関するセクションで説明しています。This behavior is discussed in the User Config section of the Cookiecutter documentation.

テンプレートでコード生成後に特定の Visual Studio タスクを実行するように指定した場合は、[Run additional tasks on completion (完了時に追加タスクを実行)] オプションが表示されます。このオプションで、それらのタスクを実行しないように選択することもできます。If the template specifies specific Visual Studio tasks to run after code generation, an additional Run additional tasks on completion option appears that allows you to opt out of those tasks. 最も一般的なタスクの使用方法としては、Web ブラウザーを開く、エディターでファイルを開く、依存関係をインストールするなどがあります。The most common use of tasks is to open a web browser, open files in the editor, install dependencies, and so on.

作成Create

オプションを設定したら、[作成] を選択してコードを生成します (出力フォルダーが空ではない場合は警告が表示されます)。Once you've set your options, select Create to generate code (a warning appears if the output folder isn't empty). テンプレートの出力に慣れていてファイルを上書きしても問題ない場合は、警告を無視してかまいません。If you're familiar with the template's output and don't mind overwriting files, you can dismiss the warning. それ以外の場合は、[キャンセル] を選択し、空のフォルダーを指定して、作成したファイルを空でない出力フォルダーに手動でコピーします。Otherwise, select Cancel, specify an empty folder, and then manually copy the created files to your non-empty output folder.

ファイルが正常に作成されると、ファイルをソリューション エクスプローラーで開くためのオプションが Cookiecutter に表示されます。After the files are created successfully, Cookiecutter provides an option to open the files in Solution Explorer:

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

Cookiecutter のオプションCookiecutter options

Cookiecutter のオプションは、[ツール] > [オプション] > [Cookiecutter] から表示できます。Cookiecutter options are available through Tools > Options > Cookiecutter:

Cookiecutter のオプション

オプションOption 説明Description
Recommended Feed URL (推奨フィードの URL)Recommended Feed URL 推奨されるテンプレート フィードの場所です。The location of the recommended templates feed. URL またはローカル ファイルへのパスを指定できます。It can be a URL or a path to a local file. マイクロソフトによって選別された既定のフィードを使用する場合は、URL を空のままにします。Leave the URL empty to use the default Microsoft curated feed. フィードでは、改行で区切られたテンプレートの場所の単純なリストが提供されます。The feed provides a simple list of template locations, separated by newlines. 選別されたフィードの変更を要求するには、GitHub 上のソースに対してプル要求を行います。To request changes to the curated feed, make a pull request against the source on GitHub.
ヘルプの表示Show Help Cookiecutter ウィンドウの上部にヘルプ情報のバーを表示するかどうかを指定します。Controls the visibility of the help information bar at the top of the Cookiecutter window.

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

Cookiecutter テンプレートの作成の基本については、Cookiecutter のドキュメントをご覧ください。For the basics of authoring a Cookiecutter template, see the Cookiecutter documentation. Visual Studio の Cookiecutter 拡張機能は、Cookiecutter v1.4 用に作成されたテンプレートをサポートします。The Cookiecutter extension for Visual Studio supports templates created for Cookiecutter v1.4.

テンプレート変数の既定のレンダリングは、データの型 (文字列またはリスト) によって異なります。The default rendering of template variables depends on the type of data (string or list):

  • 文字列: 変数名のラベル、値を入力するためのテキスト ボックス、既定値を表示するウォーターマーク。String: Label for variable name, text box for entering value, and a watermark showing the default value. テキスト ボックスのツールヒントには既定値が表示されます。Tooltip on the text box shows the default value.
  • リスト: 変数名のラベル、値を選択するためのコンボ ボックス。List: Label for variable name, combo box for selecting a value. コンボ ボックスのツールヒントには既定値が表示されます。Tooltip on the combo box shows the default value.

このレンダリングは、Visual Studio に固有の (Cookiecutter CLI では無視される) cookiecutter.json ファイルで追加のメタデータを指定することによって改善できます。It's possible to improve on this rendering by specifying additional metadata in your cookiecutter.json file that's specific to Visual Studio (and ignored by the Cookiecutter CLI). すべてのプロパティは省略可能です。All properties are optional:

プロパティProperty 説明Description
group1Label エディターの上部に、変数名の代わりに変数に対して表示される内容を指定します。Specifies what appears above the editor for the variable, instead of the name of the variable.
説明Description 編集コントロールに、変数の既定値の代わりに表示されるツールヒントを指定します。Specifies the tooltip that appears on the edit control, instead of the default value for that variable.
URLURL ラベルをハイパーリンクに変更し、URL を示したツールヒントとともに表示します。Changes the label into a hyperlink, with a tooltip that shows the URL. ハイパーリンクをクリックすると、ユーザーの既定のブラウザーでその URL が開きます。Clicking on the hyperlink opens the user's default browser to that URL.
[セレクター]Selector 変数のエディターをカスタマイズできます。Allows customization of the editor for a variable. 現在、次のセレクターがサポートされています。The following selectors are currently supported:
  • string: 標準のテキスト ボックス (文字列の既定値)。string: Standard text box, default for strings.
  • list: 標準のコンボ ボックス (リストの既定値)。list: Standard combo box, default for lists.
  • yesno: yn のいずれかを選択するコンボ ボックス (文字列用)。yesno: Combo box to choose between y and n, for strings.
  • odbcConnection: データベース接続ダイアログを起動する "..." ボタンのあるテキスト ボックス。odbcConnection: Text box with a "..." button that brings up a database connection dialog.

例:Example:

{
    "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 タスクの実行Running Visual Studio tasks

Cookiecutter には、ファイルの生成後に任意の Python コードを実行できる Post-Generate Hooks (生成後フック) と呼ばれる機能があります。Cookiecutter has a feature called Post-Generate Hooks that allows for running arbitrary Python code after the files are generated. この機能は柔軟ですが、Visual Studio への簡単なアクセスを許可しません。Although flexible, it doesn't allow easy access to Visual Studio.

たとえば、Visual Studio のエディターまたは Web ブラウザーでファイルを開くか、ユーザーに仮想環境を作成してパッケージの要件をインストールするように求める Visual Studio UI をトリガーする必要があるとします。For example, you may want to open a file in the Visual Studio editor, or in its web browser, or trigger the Visual Studio UI that prompts the user to create a virtual environment and install package requirements.

これらのシナリオを可能にするために、Visual Studio は、生成されたファイルをユーザーがソリューション エクスプローラーで開いた後または既存のプロジェクトにファイルが追加された後に実行するコマンドについて説明した拡張メタデータをcookiecutter.json 内で探しますTo allow these scenarios, Visual Studio looks for extended metadata in cookiecutter.json that describes the commands to run after the user opens the generated files in Solution Explorer or after the files are added to an existing project. (前述したように、ユーザーはテンプレート オプションの [Run additional tasks on completion (完了時に追加タスクを実行)] をオフにすることでタスクを実行しないよう選択できます)。(Again, the user can opt out of running the tasks by clearing Run additional tasks on completion in the template options.)

例:Example:

"_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 のローカライズされたインストールで動作するように、ローカライズされていない (英語の) 名前を使用する必要があります。Commands are specified by name, and should use the non-localized (English) name to work on localized installs of Visual Studio. Visual Studio のコマンド ウィンドウで、コマンド名のテストと検索を行うことができます。You can test and discover command names in the Visual Studio Command Window.

1 つの引数を渡す場合は、前の例のように文字列として指定します。If you want to pass a single argument, specify it as a string like in the previous example.

引数を渡す必要がない場合は、空の文字列のままにするか、JSON から省略します。If you don't need to pass an argument, leave it an empty string or omit it from the JSON:

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

複数の引数の場合は配列を使用します。Use an array for multiple arguments. スイッチの場合には、正しく引用されるように、スイッチとその値を別の引数に分けます。For switches, split the switch and its value into separate arguments and use proper quoting. 例:For example:

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

引数は他の Cookiecutter 変数を参照できます。Arguments can refer to other Cookiecutter variables. 上の例では、生成されたファイルへの絶対パスを作成するために内部の _output_folder_path 変数が使用されています。In the examples above, the internal _output_folder_path variable is used to form an absolute path to generated files.

Python.InstallProjectRequirements コマンドは、既存のプロジェクトにファイルを追加する場合にのみ機能します。Note that the Python.InstallProjectRequirements command works only when adding files to an existing project. ソリューション エクスプローラーの Python プロジェクトによって処理されますが、ソリューション エクスプローラーのフォルダー ビューの表示中はメッセージを受け取るプロジェクトがないため、この制限が存在します。This limitation exists because the command is processed by the Python project in Solution Explorer, and there's no project to receive the message while in Solution Explorer - Folder View. 今後のリリースでこの制限が解消され、フォルダー ビューのサポート全般が改善される可能性があります。We hope to remove the limitation win a future release (and provide better Folder View support in general).

トラブルシューティングTroubleshooting

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

一部のテンプレートの cookiecutter.json 内で、ブール型などの無効なデータ型が使用されている場合があります。Some templates may be using invalid data types, such as boolean, in their cookiecutter.json. このような場合は、[テンプレート情報] ウィンドウの [問題] リンクを選択してテンプレート作成者に報告してください。Report such instances to the template author by selecting the Issues link in the template information pane.

フック スクリプトの失敗Hook script failed

一部のテンプレートで、Cookiecutter UI と互換性のない生成後スクリプトが使用されている場合があります。Some templates may use post-generation scripts that are not compatible with the Cookiecutter UI. たとえば、ユーザーに入力をクエリするスクリプトは、端末コンソールがないため失敗します。For example, scripts that query the user for input fails due to not having a terminal console.

Windows でサポートされていないフック スクリプトHook script not supported on Windows

事後スクリプトが .sh の場合、ご使用の Windows コンピューター上のアプリケーションへの関連付けができない場合があります。If the post script is .sh, then it may not be associated with an application on your Windows machine. 互換性のあるアプリケーションを Windows ストアで見つけるように求める Windows ダイアログが表示される可能性があります。You may see a Windows dialog asking you to find a compatible application in the Windows store.

既知の問題があるテンプレートTemplates with known issues

複製エラーClone failures:

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

読み込みエラーLoad failures:

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

実行エラーRun failures:

  • iknite/cookiecutter-ansible-role (事後フック スクリプトにコンソール入力が必要)iknite/cookiecutter-ansible-role (post hook script requires console input)
  • benregn/cookiecutter-django-ansible (Jinja エラー)benregn/cookiecutter-django-ansible (Jinja error)

バッシュの使用 (致命的ではない)Uses bash (not fatal):

  • openstack-dev/cookiecutteropenstack-dev/cookiecutter