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

使用 Cookiecutter Explorer

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

瀏覽範本

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

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

   

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

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

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

複製範本

您可以在 Cookiecutter Explorer 中使用現有的範本，並建立本機副本以便進行作業。

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

   

   範本摘要包含範本詳細信息的連結。 您可以移至樣本的 GitHub 存放庫頁面、檢視範本 Wiki，或尋找回報 問題。

2. 若要複製選取的樣本，請選擇 [下一步]。 Cookiecutter 會製作範本的本地副本。

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

設定範本選項

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

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

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

1. 在 「創建至」欄位中，輸入由 Cookiecutter 生成的檔案的資料夾路徑位置。

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

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

使用組態檔設定預設值

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

退出指定的任務

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

從範本建立程序代碼

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

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

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

   

   Cookiecutter 會產生程序代碼。 如果輸出資料夾不是空的，就會顯示警告。

   • 如果您熟悉範本的輸出，且不介意覆寫檔案，請選取 確定 以關閉警告。

   • 否則，請選取 取消，指定空白資料夾，然後手動將已建立的檔案複製到非空的輸出資料夾。

2. Cookiecutter 成功建立檔案之後，Visual Studio 會在 [方案總管] 中開啟範本項目檔。

設定 Cookiecutter 選項

Cookiecutter 選項可透過 Tools>Options>Cookiecutter使用：

優化Visual Studio的 Cookiecutter 範本

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

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

• String：String 數據類型會使用變數名稱的標籤、輸入值的文字框，以及顯示預設值的浮水印。 文字框中的工具提示會顯示預設值。
• List：清單數據類型會使用變數名稱的標籤，並使用下拉式方塊來選取值。 下拉式方塊上的工具提示會顯示預設值。

您可以透過在 Visual Studio 特定的 cookiecutter.json 檔案中指定其他元資料來改善呈現（此部分會被 Cookiecutter CLI 忽略）。 所有屬性都是選擇性的：

下列範例示範如何設定轉譯屬性：

{
    "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://zcusa.951200.xyz"
    },
    {
        "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 Explorer的範本摘要中使用 問題 連結，來找出這個範本是否有已知問題：

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

相關內容

• Python 項目範本參考
• Cookiecutter：更佳的專案範本