使用 Cookiecutter 扩展

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

>在 Visual Studio 中，Cookiecutter 扩展在“查看”“Cookiecutter 资源管理器”下提供：

先决条件

• 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 资源管理器”中，可以浏览和选择模板、将模板克隆到本地计算机、设置模板选项以及从模板创建代码。

浏览模板

可以在“Cookiecutter 资源管理器”中浏览模板，查看已安装的内容和可用内容。

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

   

   主页上显示可选择的模板列表，分为四个可能的组：

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

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

克隆模板

可以在“Cookiecutter 资源管理器”中使用可用的模板，以便从中生成本地副本。

1. 在“Cookiecutter 资源管理器”中，选择模板。 有关所选模板的信息显示在“Cookiecutter 资源管理器”主页底部。

   

   模板摘要包含有关模板的详细信息的链接。 可以转到模板的 GitHub 存储库页、查看模板 Wiki 或查找所报告的问题。

2. 若要克隆所选模板，请选择“下一步”。 Cookiecutter 会生成模板的本地副本。

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

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

重要

Cookiecutter 模板将克隆到单个文件夹 ~/.cookiecutters 下。 每个子文件夹将以 Git 存储库的名称命名（不包括 GitHub 用户名）。 如果克隆来作者不同但名称相同的模板，则可能会产生冲突。 在这种情况下，Cookiecutter 将阻止使用具有相同名称的其他模板覆盖现有模板。 若要安装其他模板，必须先删除现有模板。

设置模板选项

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

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

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

1. 在“创建到”字段中，输入 Cookiecutter 生成的所有文件的文件夹路径位置。

2. 接下来，为模板设置其他所需选项，例如：

   • full_name：要应用于模板的全名。
   • 电子邮件：模板作者的电子邮件地址。
   • github_username：模板作者的 GitHub 别名。
   • python_version：从模板创建的 Web 应用的目标 Python 版本。

使用配置文件设置默认值

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

选择退出指定的任务

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

根据模板创建代码

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

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

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

   

   Cookiecutter 将生成代码。 如果输出文件夹不为空，将显示警告。

   • 如果你对模板的输出很熟悉并且不介意覆盖文件，请选择“确定”忽略该警告。

   • 否则，请选择“取消”，指定一个空文件夹，然后将创建的文件手动复制到非空的输出文件夹。

2. Cookiecutter 成功创建文件后，Visual Studio 将在“解决方案资源管理器”中打开模板项目文件。

设置 Cookiecutter 选项

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

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

优化用于 Visual Studio 的 Cookiecutter 模板

用于 Visual Studio 的 Cookiecutter 扩展支持创建用于 Cookiecutter v1.4 的模板。 有关创作 Cookiecutter 模板的更多信息，请参阅 Cookiecutter 文档。

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

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

通过在特定于 Visual Studio 的 cookiecutter.json 文件（并且 Cookiecutter CLI 忽略了该文件）中指定其他元数据，可以改进此呈现。 所有属性都是可选的：

Property	说明
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 资源管理器”中的模板摘要中使用“问题”链接来了解模板是否存在已知问题：

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

相关内容

• Python 项模板引用
• Cookiecutter：更好的项目模板