如何：搭配專案範本使用精靈

發行項
07/20/2022

適用于：Visual Studio Visual Studio for Mac Visual Studio Code

Visual Studio 提供 IWizard 介面，當實作時，可讓您在使用者從範本建立專案時執行自訂程式碼。

專案範本自訂可用來顯示自訂 UI，以收集使用者輸入來自訂範本、將其他檔案新增至範本，或專案上允許的任何其他動作。

介面 IWizard 方法會在建立專案時于各種時間呼叫，只要使用者按一下 [新增專案] 對話方塊上的 [確定] 即可開始。介面的每個方法都會命名為，以描述其呼叫點。例如，Visual Studio 會在開始建立專案時立即呼叫 RunStarted ，使其成為撰寫自訂程式碼以收集使用者輸入的好位置。

使用 VSIX 專案建立專案範本專案

您開始使用專案範本專案來建立自訂範本，這是 Visual Studio SDK 的一部分。在此程式中，我們將使用 C# 專案範本專案，但也有 Visual Basic 專案範本專案。然後將 VSIX 專案新增至包含專案範本專案的方案。

在 Visual Studio 中建立 C# 專案範本專案 (，選取 [檔案>新增>專案]，然後搜尋「project template」) 。將它命名為 MyProjectTemplate。

注意

系統可能會要求您安裝 Visual Studio SDK。如需詳細資訊，請參閱安裝 Visual Studio SDK。
在 [方案總管] 中，將新的 VSIX 專案新增至與專案範本專案相同的方案中 (，選取方案節點，然後按一下滑鼠右鍵，然後選取 [新增>專案]，然後搜尋「vsix」) 。將它命名為 MyProjectWizard。
將 VSIX 專案設定為啟始專案。在 [方案總管] 中，選取 VSIX 專案節點，以滑鼠右鍵按一下，然後選取 [ 設定為啟始專案]。
將範本專案新增為 VSIX 專案的資產。在 [方案總管] 的 VSIX 專案節點下，尋找 source.extension.vsixmanifest 檔案。按兩下它，即可在資訊清單編輯器中開啟它。
在資訊清單編輯器中，選取視窗左側的 [ 資產] 索引 標籤。
在 [ 資產] 索引卷 標中，選取 [ 新增]。在 [ 新增資產] 視窗中，針對 [類型] 欄位，選取 [Microsoft.VisualStudio.ProjectTemplate]。在 [ 來源] 欄位中，選取 目前方案中的專案。在 [ 專案] 欄位中，選取 [MyProjectTemplate]。然後按一下 [確定]。
建置方案並開始偵錯。 Visual Studio 的第二個執行個體隨即出現。 (這可能需要數分鐘的時間)。
在 Visual Studio 的第二個實例中，嘗試使用新的範本建立新的專案， ([檔案>新>專案]，搜尋「myproject」) 。新的專案應該會出現名為 Class1 的類別。您現在已建立自訂專案範本！立即停止偵錯。

建立自訂範本精靈

此程式示範如何建立自訂精靈，以在建立專案之前開啟 Windows Form。表單可讓使用者在專案建立期間新增至原始程式碼的自訂參數值。

設定 VSIX 專案以允許它建立元件。
在 [方案總管]中，選取 VSIX 專案節點。在 [方案總管] 下方，您應該會看到 [ 屬性 ] 視窗。如果沒有，請選取 [檢視>屬性視窗]，或按F4。在 [ 屬性 ] 視窗中，選取下欄欄位至 true ：
- 在 VSIX 容器中包含元件
- 在本機 VSIX 部署中包含偵錯符號
- 在 VSIX 容器中包含偵錯符號
將元件新增為 VSIX 專案的資產。開啟 source.extension.vsixmanifest 檔案，然後選取 [ 資產] 索引卷 標。在 [ 新增資產] 視窗中，針對 [類型 ] 選取 [Microsoft.VisualStudio.Assembly]，針對 [ 來源 ] 選取 [目前方案中的專案]，然後針對 [ 專案 ] 選取 [MyProjectWizard]。
將下列參考新增至 VSIX 專案。 (在 [方案總管] 的 VSIX 專案節點下，選取 [ 參考]，以滑鼠右鍵按一下，然後選取 [ 新增參考]。) 在 [ 新增參考 ] 對話方塊中，在 [ 架構 ] 索引標籤中，尋找 System.Windows Forms 元件並加以選取。另請尋找並選取 System 和 System.Drawing 元件。現在選取 [ 延伸模組] 索引卷 標。尋找 EnvDTE 元件並加以選取。另請尋找 Microsoft.VisualStudio.TemplateWizardInterface 元件並加以選取。按一下 [確定]。
將精靈實作的類別新增至 VSIX 專案。 (在 [方案總管] 中，以滑鼠右鍵按一下 VSIX 專案節點，然後選取 [ 新增]、[ 新增專案]、[ Class.) 命名類別 WizardImplementation]。

以下列程式碼取代 WizardImplementationClass.cs 檔案中的程式碼：

using System;
using System.Collections.Generic;
using Microsoft.VisualStudio.TemplateWizard;
using System.Windows.Forms;
using EnvDTE;

namespace MyProjectWizard
{
    public class WizardImplementation:IWizard
    {
        private UserInputForm inputForm;
        private string customMessage;

        // This method is called before opening any item that
        // has the OpenInEditor attribute.
        public void BeforeOpeningFile(ProjectItem projectItem)
        {
        }

        public void ProjectFinishedGenerating(Project project)
        {
        }

        // This method is only called for item templates,
        // not for project templates.
        public void ProjectItemFinishedGenerating(ProjectItem
            projectItem)
        {
        }

        // This method is called after the project is created.
        public void RunFinished()
        {
        }

        public void RunStarted(object automationObject,
            Dictionary<string, string> replacementsDictionary,
            WizardRunKind runKind, object[] customParams)
        {
            try
            {
                // Display a form to the user. The form collects
                // input for the custom message.
                inputForm = new UserInputForm();
                inputForm.ShowDialog();

                customMessage = UserInputForm.CustomMessage;

                // Add custom parameters.
                replacementsDictionary.Add("$custommessage$",
                    customMessage);
            }
            catch (Exception ex)
            {
                MessageBox.Show(ex.ToString());
            }
        }

        // This method is only called for item templates,
        // not for project templates.
        public bool ShouldAddProjectItem(string filePath)
        {
            return true;
        }
    }
}

稍後將會實作此程式碼中所參考 的 UserInputForm 。

類別 WizardImplementation 包含每個成員的方法 IWizard 實作。在此範例中 RunStarted ，只有方法會執行工作。所有其他方法都不會執行任何動作或傳回 true 。

方法 RunStarted 接受四個參數：

Object可轉換成根 _DTE 物件的參數，可讓您自訂專案。
Dictionary<TKey,TValue>參數，其中包含範本中所有預先定義之參數的集合。如需範本參數的詳細資訊，請參閱範本參數。
WizardRunKind參數，其中包含正在使用何種範本的相關資訊。
Object陣列，包含 Visual Studio 傳遞至精靈的一組參數。

本範例會將使用者輸入表單中的參數值新增至 Dictionary<TKey,TValue> 參數。專案中參數的每個實例 $custommessage$ 都會取代為使用者輸入的文字。

現在建立 UserInputForm。在 WizardImplementation.cs 檔案中，于類別結尾 WizardImplementation 處新增下列程式碼。

public partial class UserInputForm : Form
    {
        private static string customMessage;
        private TextBox textBox1;
        private Button button1;

        public UserInputForm()
        {
            this.Size = new System.Drawing.Size(155, 265);

            button1 = new Button();
            button1.Location = new System.Drawing.Point(90, 25);
            button1.Size = new System.Drawing.Size(50, 25);
            button1.Click += button1_Click;
            this.Controls.Add(button1);

            textBox1 = new TextBox();
            textBox1.Location = new System.Drawing.Point(10, 25);
            textBox1.Size = new System.Drawing.Size(70, 20);
            this.Controls.Add(textBox1);
        }
        public static string CustomMessage
        {
            get
            {
                return customMessage;
            }
            set
            {
                customMessage = value;
            }
        }
        private void button1_Click(object sender, EventArgs e)
        {
            customMessage = textBox1.Text;
            this.Close();
        }
    }

使用者輸入表單提供簡單的表單來輸入自訂參數。表單包含名為的 textBox1 文字方塊，以及名為的 button1 按鈕。按一下按鈕時，文字方塊的文字會儲存在參數中 customMessage 。

將精靈連線至自訂範本

為了讓自訂專案範本使用自訂精靈，您必須簽署精靈元件，並將一些程式程式碼新增至自訂專案範本，讓它知道在建立新專案時要在哪裡尋找精靈實作。

簽署元件。在 [ 方案總管] 中，選取 VSIX 專案，按一下滑鼠右鍵，然後選取 [ 專案屬性]。
在 [ 專案屬性 ] 視窗中，選取 [ 簽署 ] 索引標籤。在 [ 簽署 ] 索引標籤中，勾選 [簽署元件]。在 [選擇強式名稱金鑰檔案] 欄位中，選取 [< 新增 >]。在 [ 建立強式名稱金鑰] 視窗中的 [ 金鑰檔案名 ] 欄位中，輸入 key.snk。取消核取 [使用密碼] 欄位保護我的金鑰檔案 。
在 [ 方案總管] 中，選取 VSIX 專案並尋找 [ 屬性 ] 視窗。
將 [ 複製組建輸出] 設定為 [輸出目錄 ] 欄位為 true。這可讓元件在重建解決方案時複製到輸出目錄中。它仍然包含在檔案中 .vsix 。您必須查看元件，才能找出其簽署金鑰。
重建方案。
您現在可以在 MyProjectWizard 專案目錄中找到 key.snk 檔案， (< 磁片位置 > \MyProjectTemplate\MyProjectWizard\key.snk) 。複製 key.snk 檔案。
移至輸出目錄，並尋找磁片位置 > \MyProjectTemplate/MyProjectWizard\bin\Debug\MyProjectWizard.dll) (元件 < 。在這裡貼上 key.snk 檔案。 (這並非絕對必要，但會讓下列步驟更容易。)
開啟命令視窗，並變更為已建立元件的目錄。
尋找 sn.exe 簽署工具。例如，在 Windows 10 64 位作業系統上，典型的路徑如下：

C：\Program Files (x86) \Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.6.1 Tools

如果您找不到此工具，請嘗試在命令視窗中執行 /R 。 sn.exe的位置 。記下路徑。
從 key.snk 檔案擷取公開金鑰。在命令視窗中，輸入

<sn.exe>\sn.exe -p key.snk outfile.key 的位置。

如果目錄名稱中有空格，別忘了以引號括住 sn.exe 的路徑！
從 outfile 取得公開金鑰權杖：

<sn.exe>\sn.exe -t outfile.key 的位置。

同樣地，別忘了引號。您應該會在輸出中看到一行，如下所示

公開金鑰權杖是 < 權杖>

記下此值。
將自訂精靈的參考新增至專案範本的 .vstemplate 檔案。在 [方案總管] 中，尋找名為 MyProjectTemplate.vstemplate 的檔案，然後加以開啟。在 TemplateContent > 區段結束 < 之後，新增下列區段：
```
<WizardExtension>
    <Assembly>MyProjectWizard, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=token</Assembly>
    <FullClassName>MyProjectWizard.WizardImplementation</FullClassName>
</WizardExtension>
```
其中 MyProjectWizard 是元件的名稱，而 Token 是您在上一個步驟中複製的權杖。
儲存專案中的所有檔案並重建。

將自訂參數新增至範本

在此範例中，做為範本的專案會顯示自訂精靈的使用者輸入表單中指定的訊息。

在 [方案總管] 中，移至 MyProjectTemplate 專案，然後開啟 Class1.cs。
在 Main 應用程式的方法中，新增下列程式程式碼。
```
Console.WriteLine("$custommessage$");
```
從範本建立專案時，參數 $custommessage$ 會取代為使用者輸入表單中輸入的文字。

以下是匯出至範本之前的完整程式碼檔案。

using System;
using System.Collections.Generic;
$if$ ($targetframeworkversion$ >= 3.5)using System.Linq;
$endif$using System.Text;

namespace $safeprojectname$
{
    public class Class1
    {
          static void Main(string[] args)
          {
               Console.WriteLine("$custommessage$");
          }
    }
}

使用自訂精靈

現在您可以從範本建立專案，並使用自訂精靈。

重建方案並開始偵錯。 Visual Studio 的第二個執行個體應該會出現。
建立新的 MyProjectTemplate 專案。 (檔案>新>專案) 。
在 [ 新增專案 ] 對話方塊中，搜尋「myproject」以找出您的範本、輸入名稱，然後按一下 [ 確定]。

精靈使用者輸入表單隨即開啟。
輸入自訂參數的值，然後按一下按鈕。

精靈使用者輸入表單會關閉，並從範本建立專案。
在 [方案總管]中，以滑鼠右鍵按一下原始程式碼檔案，然後按一下 [ 檢視程式碼]。

請注意， $custommessage$ 已取代為精靈使用者輸入表單中輸入的文字。