使用 Cookiecutter 延伸模組

文章
04/18/2024

Cookiecutter (英文) 提供尋找範本、輸入範本選項和建立專案及檔案的圖形化使用者介面。 Visual Studio 2017 和更新版本包含 Cookiecutter 擴充功能。它可以個別安裝在舊版 Visual Studio。

在 Visual Studio 中，Cookiecutter 延伸模組可在 [檢視]>[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 Explorer

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

瀏覽範本

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

在 Cookiecutter Explorer 中，選取工具欄上的 [首頁] 選項，以檢視可用的範本。

首頁會顯示可選擇的範本清單，並可分為四個群組︰

群組	描述	附註
已安裝	安裝到本機電腦的範本。使用線上範本時，其存放庫會自動複製到 ~/.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。當設定值可以變更時，欄位文字就可供編輯。

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

使用設定檔設定預設值

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

退出指定的工作

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

從範本建立程式碼

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

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

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

Cookiecutter 會產生程式碼。如果輸出資料夾不是空的，則會顯示警告。
- 如果您熟悉範本的輸出，而且不介意覆寫檔案，您可以選取 OK 以關閉此警告。
- 否則，請選取 [取消 (Cancel)]、指定空白資料夾，並手動將建立的檔案複製到非空白的輸出資料夾。
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 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 有一個稱為 Post-Generate Hook (產生後置掛勾) 的功能，可在產生檔案之後執行任意 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 中使用無效的資料類型，例如布林值。您可以選取範本資訊窗格中的 [問題] 連結，將這類執行個體報告給範本作者。

Hook 指令碼失敗

有些範本可能使用與 Cookiecutter UI 不相容的產生後置指令碼。例如，查詢使用者輸入的指令碼將因為沒有終端機主控台而失敗。

Windows 上不支援 Hook 指令碼

如果後置指令檔為 .sh，它可能未與您 Windows 電腦上的應用程式建立關聯。您可能會看到 Windows 對話方塊，要求您在 Windows 市集尋找相容的應用程式。

含有已知問題的範本

您可以使用 Cookiecutter Explorer 範本摘要中的 [問題] 連結，瞭解範本是否有已知問題：

顯示如何在 Cookiecutter Explorer 中開啟範本的已知問題清單的螢幕擷取畫面。

該連結會開啟範本的 GitHub 問題頁面：

分享方式：

使用 Cookiecutter 延伸模組

必要條件

使用 Cookiecutter Explorer

瀏覽範本

複製範本

設定範本選項

使用設定檔設定預設值

退出指定的工作

從範本建立程式碼

設定 Cookiecutter 選項

最佳化 Visual Studio 的 Cookiecutter 範本

執行 Visual Studio 工作

範本問題疑難排解

載入範本時發生錯誤

Hook 指令碼失敗

Windows 上不支援 Hook 指令碼

含有已知問題的範本

意見反映

更多資源

分享方式：

使用 Cookiecutter 延伸模組

必要條件

使用 Cookiecutter Explorer

瀏覽範本

複製範本

設定範本選項

使用設定檔設定預設值

退出指定的工作

從範本建立程式碼

設定 Cookiecutter 選項

最佳化 Visual Studio 的 Cookiecutter 範本

執行 Visual Studio 工作

範本問題疑難排解

載入範本時發生錯誤

Hook 指令碼失敗

Windows 上不支援 Hook 指令碼

含有已知問題的範本

相關內容

意見反映

更多資源