共用方式為


使用 Cookiecutter 延伸模組

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

在 Visual Studio 中,Cookiecutter 延伸模組可在 [檢視]>[Cookiecutter Explorer] 中取得:

顯示 Visual Studio 中 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 中瀏覽範本,以查看已安裝的專案和可用的功能。

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

    顯示 Visual Studio 中 Cookiecutter Explorer 首頁的螢幕擷取畫面,其中包含 [建議] 和 [GitHub] 類別所列的範本。

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

    群組 描述 附註
    已安裝 安裝到本機電腦的範本。 使用線上範本時,其存放庫會自動複製到 ~/.cookiecutters 的子資料夾。 您可以選取 Cookiecutter Explorer 工具列上的 [刪除],從系統移除已安裝的範本。
    建議需求 從建議的摘要載入的範本。 Microsoft 會精選預設摘要。 您可以遵循設定 Cookiecutter 選項中的步驟來自訂摘要。
    GitHub 「Cookiecutter」關鍵字的 GitHub 搜尋結果。 Git 存放庫清單會以分頁形式傳回。 當結果清單超過目前檢視時,您可以選取 [載入更多] 選項,在清單中顯示下一組分頁結果。
    自訂 透過 Cookiecutter Explorer 定義的任何自訂範本。 在 Cookiecutter Explorer 搜尋方塊中輸入自訂範本位置時,位置會顯示在此群組。 您可以輸入 Git 存放庫的完整路徑,以定義一個自訂範本,或輸入本機磁碟上的資料夾完整路徑。
  2. 若要顯示或隱藏特定類別的可用範本清單,請選取類別旁的箭頭

複製範本

您可以在 Cookiecutter Explorer 中使用可用的範本來建立本機複本,以進行作業。

  1. Cookiecutter Explorer 中選取範本。 所選範本的相關資訊會顯示在 Cookiecutter Explorer 首頁底部。

    顯示如何在 Visual Studio 的 Cookiecutter Explorer 中選取複製範本的螢幕擷取畫面。

    範本摘要包含範本詳細資訊的連結。 您可以移至 範本的 GitHub 存放庫頁面、檢視範本 Wiki,或搜尋回報的問題

  2. 若要複製選取的範本,請選取 [下一步]。 Cookiecutter 會建立範本的本機複本。

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

範本類型 行為
已安裝 如果在先前的 Visual Studio 工作階段中已安裝所選取的範本,則會自動刪除,並在您的本機電腦上安裝和複製最新版本。
建議需求 選取的範本會複製並安裝在本機電腦上。
GitHub 選取的範本會複製並安裝在本機電腦上。
自訂搜尋 - URL:如果您在 Cookiecutter Explorer 搜尋方塊中輸入 Git 存放庫的自訂 URL,然後選取範本,則選取的範本會複製並安裝在本機電腦上。
- 資料夾路徑:如果您在搜尋方塊中輸入自訂資料夾路徑並選取該範本,Visual Studio 會載入該範本而不複製。

重要

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

設定範本選項

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

顯示 Visual Studio 中 Cookiecutter Explorer 中新安裝和複製範本選項的螢幕擷取畫面。

每個 Cookiecutter 範本都會定義自己的一組選項。 當預設值可供設定使用時,[選項] 頁面會顯示對應欄位中的建議文字。 預設值可以是程式碼片段 (通常在它是使用其他選項的動態值時)。

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

  1. [建立至] 欄位中,輸入 Cookiecutter 所產生的任何檔案的資料夾路徑位置。

  2. 接下來,設定範本的其他所需選項,例如:

    • full_name:要套用至範本的完整名稱。
    • email:範本作者的電子郵件位址。
    • github_username:範本作者的 GitHub 別名。
    • python_version:從範本建立之 Web 應用程式的目標 Python 版本。

使用設定檔設定預設值

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

退出指定的工作

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

從範本建立程式碼

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

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

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

    顯示範本選項清單之後 [建立和開啟資料夾] 按鈕的螢幕擷取畫面。

    Cookiecutter 會產生程式碼。 如果輸出資料夾不是空的,則會顯示警告。

    • 如果您熟悉範本的輸出,而且不介意覆寫檔案,您可以選取 OK 以關閉此警告。

    • 否則,請選取 [取消 (Cancel)]、指定空白資料夾,並手動將建立的檔案複製到非空白的輸出資料夾。

  2. Cookiecutter 順利建立檔案之後, Visual Studio 會在 [方案總管] 中開啟範本專案檔:

設定 Cookiecutter 選項

Cookiecutter 選項可透過 [工具]>[選項]>[Cookiecutter] 存取:

顯示 Visual Studio 中 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︰可在 yn 之間選擇的下拉式方塊,適用於字串。
- 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 問題頁面:

顯示 GitHub 中範本回報問題的螢幕擷取畫面。