使用 Cookiecutter 扩展

项目
02/10/2025

Cookiecutter 提供了一个图形用户界面，用于发现模板、输入模板选项以及创建项目和文件。 Visual Studio 2017 及更高版本包括 Cookiecutter 扩展。它可以单独安装在 Visual Studio 的早期版本中。

在 Visual Studio 中，Cookiecutter 扩展在 View>Cookiecutter Explorer下提供：

先决条件

Visual Studio。若要安装产品，请按照安装 Visual Studio中的步骤操作。
Python 3.3 或更高版本（32 位或 64 位）或 Anaconda 3 4.2 或更高版本（32 位或 64 位）。
- 如果合适的 Python 解释器不可用，Visual Studio 会显示警告。
- 如果在 Visual Studio 运行时安装 Python 解释器，请在 Cookiecutter 资源管理器 工具栏上选择主页选项以检测新安装的解释器。有关详细信息，请参阅在 Visual Studio中创建和管理 Python 环境。

使用 Cookiecutter 资源管理器

在 Cookiecutter Explorer中，可以浏览并选择模板、将模板克隆到本地计算机、设置模板选项，以及从模板创建代码。

浏览模板

可以在 Cookiecutter Explorer 中浏览模板，查看已安装的内容和可用内容。

在 Cookiecutter 资源管理器中，选择工具栏上的主页选项以查看可用的模板。

主页显示要从中选择的模板列表，这些模板按四个可能组进行组织：

Group	描述	笔记
已安装	模板已安装到本地计算机。使用联机模板时，其存储库会自动克隆到 ~/.cookiecutters 的子文件夹。	可以通过在 Cookiecutter Explorer 工具栏上选择删除，从系统中删除已安装的模板。
建议	从建议源加载的模板。 Microsoft管理默认信息流。	可以按照设置 Cookiecutter 选项中的步骤来自定义原。
GitHub	“cookiecutter”关键字的 GitHub 搜索结果。 git 存储库的列表以分页形式返回。	当结果列表超过当前视图时，可以选择加载更多选项以显示列表中的下一组分页结果。
自定义	通过 Cookiecutter 资源管理器定义的任何自定义模板。在 Cookiecutter Explorer 搜索框中输入自定义模板位置时，该位置将显示在此组中。	可以通过输入 git 存储库的完整路径或本地磁盘上文件夹的完整路径来定义自定义模板。

若要显示或隐藏特定类别的可用模板列表，请选择类别旁边的箭头。

克隆模板

可以在 Cookiecutter Explorer 中使用可用的模板，制作用于工作的本地副本。

在 Cookiecutter Explorer中，选择模板。有关所选模板的信息显示在 Cookiecutter Explorer 主页的底部。

模板摘要包含有关模板的详细信息的链接。可以转到模板的 GitHub 存储库页、查看模板 Wiki，或查找报告问题。
若要复制所选模板，请选择 下一步。 Cookiecutter 生成模板的本地副本。

克隆行为取决于所选模板的类型：

模板类型	行为
已安装	如果在 Visual Studio 的上一个会话中安装了所选模板，则会自动删除该模板，并在本地计算机上安装并克隆最新版本。
建议	所选模板将克隆并安装在本地计算机上。
GitHub	所选模板将克隆并安装在本地计算机上。
自定义搜索	- URL：如果将 git 存储库的自定义 URL 输入到 Cookiecutter Explorer 搜索框中，然后选择模板，则会在本地计算机上克隆并安装所选模板。 - 文件夹路径：如果在搜索框中输入自定义文件夹路径，然后选择模板，Visual Studio 将加载该模板而不克隆。

重要

Cookiecutter 模板被克隆到一个单独的文件夹中，~/.cookiecutters。每个子文件夹都以 git 存储库名称命名，不包括 GitHub 用户名。如果您克隆来自不同作者且具有相同名称的不同模板，可能会出现冲突。在这种情况下，Cookiecutter 可防止使用同名的不同模板覆盖现有模板。若要安装其他模板，必须先删除现有模板。

设置模板选项

在本地安装和克隆模板后，Cookiecutter 会显示选项页。在此页上，可以指定设置，例如生成的文件的文件夹路径位置：

每个 Cookiecutter 模板定义其自己的一组选项。当默认值可用于设置时，“选项” 页会显示相应字段中的建议文本。默认值可能是代码片段，通常是使用其他选项的动态值。

在此示例中，模板名称定义为 cookiecutter-flask/cookiecutter-flask。当设置值可以更改时，字段文本可用于编辑。

在“创建到”字段中，输入 Cookiecutter 生成的任何文件的文件夹路径。
接下来，为模板设置其他所需选项，例如：
- full_name：要应用于模板的全名。
- 电子邮件：模板作者的电子邮件地址。
- github_username：模板作者的 GitHub 别名。
- python_version：从模板创建的 Web 应用的目标 Python 版本。

使用配置文件设置默认值

可以使用用户配置文件自定义特定选项的默认值。当 Cookiecutter 扩展检测到用户配置文件时，它会使用配置文件值覆盖模板的默认值。有关此行为的详细信息，请参阅 Cookiecutter 文档的 User Config 部分。

选择退出指定的任务

某些模板标识在代码生成后要运行的特定 Visual Studio 任务。常见任务包括打开 Web 浏览器、在编辑器中打开文件以及安装依赖项。当模板标识特定任务时，设置“在完成时运行其他任务”将被添加到选项列表中。可以将此设置配置为选择退出指定的 Visual Studio 任务。

从模板创建代码

设置模板选项后，即可让 Cookiecutter 创建项目文件并生成代码。

对话框在选项列表之后显示一个按钮。按钮的文本取决于模板。你可能会看到 创建和打开文件夹、添加到解决方案等。

在选项页上，选择选项列表后面的按钮，例如 创建和打开文件夹 或 添加到解决方案。

Cookiecutter 生成代码。如果输出文件夹不为空，将显示警告。
- 如果你对模板的输出很熟悉并且不介意覆盖文件，请选择“确定”以忽略该警告。
- 否则，请选择取消，指定空文件夹，然后将创建的文件手动复制到 nonempty 输出文件夹。
Cookiecutter 成功创建文件后，Visual Studio 会在 解决方案资源管理器中打开模板项目文件。

设置 Cookiecutter 选项

通过“工具”>“选项”>“Cookiecutter”，可使用 Cookiecutter 选项：

选项	描述
检查更新的模板	控制 Cookiecutter 是否自动联机检查已安装模板的更新。
建议的源 URL	建议的模板源文件的位置。该位置可以是 URL 或本地文件的路径。将 URL 留空以使用默认 Microsoft 精选内容源。源提供了由换行符分隔的模板位置的简单列表。若要请求对精选推送进行更改，请在 GitHub 上向源提交拉取请求。
显示帮助	控制 Cookiecutter 窗口顶部帮助信息栏的可见性。

优化 Visual Studio 的 Cookiecutter 模板

Visual Studio 的 Cookiecutter 扩展支持为 Cookiecutter v1.4 创建的模板。有关创作 Cookiecutter 模板的详细信息，请参阅 Cookiecutter 文档。

模板变量的默认呈现取决于数据类型（字符串或列表）：

字符串：字符串数据类型使用变量名称的标签、用于输入值的文本框以及显示默认值的水印。文本框中的工具提示显示默认值。
List：列表数据类型使用变量名称的标签和一个组合框来选择值。组合框上的工具提示显示默认值。

要改进呈现效果，可以在特定于 Visual Studio 的 cookiecutter.json 文件中指定其他元数据（这些元数据会被 Cookiecutter CLI 忽略）。所有属性都是可选的：

财产	描述
`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 代码。虽然该功能很灵活，但它不允许轻松访问 Visual Studio。

可以使用此功能在 Visual Studio 编辑器或其 Web 浏览器中打开文件。还可以触发 Visual Studio UI，提示用户创建虚拟环境并安装包要求。

为了允许这些方案，Visual Studio 在 cookiecutter.json 文件中查找扩展元数据。它会在用户打开 解决方案资源管理器 或文件添加到现有项目之后，搜索要运行的命令。（同样，用户可以通过清除“完成后运行其他任务”模板选项，选择退出运行这些任务。）

以下示例演示如何在 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 命令窗口中测试和发现命令名称。

如果要传递单个参数，请将参数指定为字符串，如上一示例中的 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 文件中可能会使用无效的数据类型，例如布尔值。可以通过在模板信息窗格中选择问题链接，将这些实例报告给模板作者。

挂钩脚本失败

某些模板可能使用与 Cookiecutter UI 不兼容的生成后脚本。例如，由于缺少终端控制台，查询用户输入的脚本可能会失败。

Windows 不支持挂钩脚本

如果发布脚本文件 .sh，它可能不会与 Windows 计算机上的应用程序相关联。你可能会看到 Windows 对话框提示，用于在 Windows 应用商店中找到兼容的应用程序。

具有已知问题的模板

可以使用 Cookiecutter 资源管理器中的模板摘要中的问题链接来确定模板是否存在已知问题：

屏幕截图，显示如何在 Cookiecutter 资源管理器中打开模板的已知问题列表。

该链接将打开模板的 GitHub 问题页：

通过

使用 Cookiecutter 扩展

先决条件

使用 Cookiecutter 资源管理器

浏览模板

克隆模板

设置模板选项

使用配置文件设置默认值

选择退出指定的任务

从模板创建代码

设置 Cookiecutter 选项

优化 Visual Studio 的 Cookiecutter 模板

运行 Visual Studio 任务

排查模板问题

加载模板时出错

挂钩脚本失败

Windows 不支持挂钩脚本

具有已知问题的模板

反馈

其他资源

通过

使用 Cookiecutter 扩展

先决条件

使用 Cookiecutter 资源管理器

浏览模板

克隆模板

设置模板选项

使用配置文件设置默认值

选择退出指定的任务

从模板创建代码

设置 Cookiecutter 选项

优化 Visual Studio 的 Cookiecutter 模板

运行 Visual Studio 任务

排查模板问题

加载模板时出错

挂钩脚本失败

Windows 不支持挂钩脚本

具有已知问题的模板

相关内容

反馈

其他资源