使用 Cookiecutter 擴充功能

發行項
01/26/2025

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 Explorer 工具列上選取 [Home] 選項，以偵測新安裝的解釋器。如需詳細資訊，請參閱在 Visual Studio中建立和管理 Python 環境。

使用 Cookiecutter Explorer

在 Cookiecutter Explorer中，您可以瀏覽和選取範本、將範本複製到本機計算機、設定範本選項，以及從範本建立程式碼。

瀏覽範本

您可以在 Cookiecutter Explorer 中瀏覽範本，以查看已安裝的專案和可用的專案。

在 Cookiecutter Explorer中，選取工具列上的 Home 選項，以檢視可用的範本。

首頁會顯示要從中選擇的範本清單，並組織成四個可能群組：

群	描述	筆記
已安裝	安裝到本機計算機的範本。使用在線範本時，其存放庫會自動複製到 ~/.cookiecutters 的子資料夾。	您可以在 Cookiecutter Explorer 工具列上選取 [刪除]，以從系統移除已安裝的範本。
建議	從推薦資訊流載入的範本。 Microsoft管理預設資訊流。	您可以按照設定 Cookiecutter 選項中的步驟來自定義您的資訊流。
GitHub	“cookiecutter” 關鍵詞的 GitHub 搜尋結果。 Git 存放庫清單會以分頁形式傳回。	當結果清單超過目前的檢視時，您可以選取 [載入更多] 選項，以顯示清單中的下一組編頁結果。
自定義	透過 Cookiecutter Explorer定義的任何自定義範本。在 Cookiecutter Explorer 搜尋方塊中輸入自定義範本位置時，位置會出現在此群組中。	您可以輸入 Git 存放庫的完整路徑，或本機磁碟上資料夾的完整路徑，來定義自定義範本。

若要顯示或隱藏特定類別的可用範本清單，請選取類別旁的箭號。

複製範本

您可以在 Cookiecutter Explorer 中使用可用的範本，建立當地的複本以便開始工作。

在 Cookiecutter Explorer中，選取範本。所選範本的相關信息會顯示在 Cookiecutter Explorer 首頁底部。

範本摘要包含範本詳細信息的連結。您可以移至樣本的 GitHub 存放庫頁面、檢視範本 Wiki，或尋找回報問題。
若要複製選取的樣本，請選擇 [下一步] 。 Cookiecutter 會製作範本的本地副本。

複製行為取決於您選取的範本類型：

範本類型	行為
已安裝	如果選取的範本已安裝在 Visual Studio 的上一個工作階段中，系統會自動刪除該範本，並在本機電腦上安裝並複製最新版本。
建議	選取的範本會複製並安裝在本機電腦上。
GitHub	選取的範本會複製並安裝在本機電腦上。
自定義搜尋	- URL：如果您在 Cookiecutter Explorer 搜尋框中輸入 git 存放庫的自定義 URL，然後選擇範本，選擇的範本將會被克隆並安裝到您的本地電腦上。 - 資料夾路徑：如果您在搜尋方塊中輸入自定義資料夾路徑，然後選取範本，Visual Studio 會載入該範本而不複製。

重要

Cookiecutter 範本會在 ~/.cookiecutters 的單一資料夾下複製。每個子資料夾都會以 Git 存放庫名稱命名，其中不包含 GitHub 用戶名稱。如果您複製來自不同作者之相同名稱的不同範本，就可能發生衝突。在此情況下，Cookiecutter 會防止您使用相同名稱的不同範本覆寫現有的範本。若要安裝其他範本，您必須先刪除現有的範本。

設定範本選項

在本機安裝和複製範本之後，Cookiecutter 會顯示 [選項] 頁面。在這裡頁面上，您可以指定設定，例如所產生檔案的資料夾路徑位置：

每個 Cookiecutter 範本都會定義自己的一組選項。當設定有預設值可用時，[選項] 頁面會在對應的欄位中顯示建議的文字。預設值可能是代碼段，通常是使用其他選項的動態值。

在這個範例中，範本名稱被定義為 cookiecutter-flask/cookiecutter-flask。當設定值可以變更時，欄位文字就可供編輯。

在 [Create to] 欄位中，輸入資料夾的路徑位置，以儲存 Cookiecutter 所生成的任何檔案。
接下來，設定範本的其他所需選項，例如：
- full_name：要套用至範本的完整名稱。
- 電子郵件：範本作者的電子郵件位址。
- github_username：範本作者的 GitHub 別名。
- python_version：從範本建立之 Web 應用程式的目標 Python 版本。

使用組態檔設定預設值

您可以使用使用者組態檔自定義特定選項的預設值。當 Cookiecutter 延伸模組偵測到使用者組態檔時，它會以組態檔值覆寫範本的預設值。如需此行為的詳細資訊，請參閱 Cookiecutter 檔用戶設定一節。

退訂指定的任務

某些範本會識別在程式代碼產生之後要執行的特定Visual Studio工作。一般工作包括開啟網頁瀏覽器、在編輯器中開啟檔案，以及安裝相依性。當範本識別特定工作時，在完成時執行其他工作 設定會新增至選項清單。您可以設定此設定來選擇退出指定的 Visual Studio 工作。

從範本建立程序代碼

設定範本選項之後，您就可以讓 Cookiecutter 建立專案檔併產生程式代碼。

對話框會在選項清單之後顯示按鈕。按鈕的文字取決於範本。您可能會看到 [建立和開啟資料夾]、[加入方案]等等。

在 [選項] 頁面上，選取遵循選項清單的按鈕，例如 建立和開啟資料夾 或 [新增至方案]。

Cookiecutter 會產生程序代碼。如果輸出資料夾不是空的，就會顯示警告。
- 如果您熟悉範本的輸出，且不介意覆寫檔案，請選取 [確定] 關閉警告。
- 否則，請選取 Cancel，指定空白資料夾，然後手動將建立的檔案複製到非空的輸出資料夾。
Cookiecutter 成功建立檔案之後，Visual Studio 會在 [方案總管] 中開啟範本項目檔。

設定 Cookiecutter 選項

Cookiecutter 選項可透過 Tools>Options>Cookiecutter取得：

選項	描述
檢查更新的範本	控制 Cookiecutter 是否會自動在線檢查已安裝範本的更新。
建議的資訊流 URL	建議範本摘要檔案的位置。位置可以是 URL 或本機檔案的路徑。將 URL 保留空白，以便使用預設的 Microsoft 精選內容。摘要提供範本位置的簡單清單，並以換行符分隔。若要要求對策展摘要進行變更，請對 GitHub 上的來源提出提取要求。
顯示說明	調整 Cookiecutter 視窗頂端說明資訊列的可見性。

優化Visual Studio的 Cookiecutter 範本

Visual Studio 的 Cookiecutter 擴充功能支持針對 Cookiecutter v1.4 建立的範本。如需撰寫 Cookiecutter 範本的詳細資訊，請參閱 Cookiecutter 檔。

樣本變數的預設轉譯取決於資料類型（字串或清單）：

String：String 數據類型會使用變數名稱的標籤、輸入值的文字框，以及顯示預設值的浮水印。文字框中的工具提示會顯示預設值。
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 具有稱為 Post-Generate Hooks 的功能，可讓您在產生檔案之後執行任意 Python 程式代碼。雖然此功能具有彈性，但不允許輕鬆存取 Visual Studio。

您可以使用此功能在 Visual Studio 編輯器或其網頁瀏覽器中開啟檔案。您也可以觸發 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 市集中尋找相容的應用程式。

已知問題的範本

您可以在 CookiecutterExplorer 的範本摘要中使用問題連結，找出範本是否有已知問題：

顯示如何在 Cookiecutter Explorer 中開啟已知問題清單的範本螢幕截圖。

鏈接會開啟範本的 GitHub 問題頁面：

共用方式為

使用 Cookiecutter 擴充功能

先決條件

使用 Cookiecutter Explorer

瀏覽範本

複製範本

設定範本選項

使用組態檔設定預設值

退訂指定的任務

從範本建立程序代碼

設定 Cookiecutter 選項

優化Visual Studio的 Cookiecutter 範本

執行 Visual Studio 工作

針對範本問題進行疑難解答

載入範本時發生錯誤

攔截腳本失敗

Windows 上不支援掛鉤腳本

已知問題的範本

意見反應

其他資源

共用方式為

使用 Cookiecutter 擴充功能

先決條件

使用 Cookiecutter Explorer

瀏覽範本

複製範本

設定範本選項

使用組態檔設定預設值

退訂指定的任務

從範本建立程序代碼

設定 Cookiecutter 選項

優化Visual Studio的 Cookiecutter 範本

執行 Visual Studio 工作

針對範本問題進行疑難解答

載入範本時發生錯誤

攔截腳本失敗

Windows 上不支援掛鉤腳本

已知問題的範本

相關內容

意見反應

其他資源