HOW TO：搭配專案範本使用精靈
更新：2007 年 11 月
Visual Studio 會提供 IWizard 介面，這個介面在實作後，可以讓您在使用者從範本建立專案時執行自訂的程式碼。
專案範本自訂可以用於：
顯示會收集使用者輸入以參數化範本的自訂 UI。
加入要在範本中使用的參數值。
將其他檔案加入範本。
在專案上執行 Visual Studio Automation 物件模型所允許的大部分動作。
建立專案時，會在不同的時間點呼叫 IWizard 介面方法，而且只要使用者按一下 [新增專案] 對話方塊上的 [確定]，就會開始呼叫。介面的每個方法是以描述呼叫方法的時間點來命名。例如，Visual Studio 會在開始建立專案時立即呼叫 RunStarted，使它成為撰寫自訂程式碼以收集使用者輸入的好位置。
您為自訂精靈所撰寫的大部分程式碼，將使用 DTE 物件 (它是 Visual Studio Automation 物件模型中的主要物件) 來自訂專案。如需 Automation 物件模型的詳細資訊，請參閱擴充 Visual Studio 環境和Automation 與擴充性參考。
建立自訂範本精靈
本主題顯示如何建立會在專案建立之前開啟 Windows Form 的自訂精靈。此表單可以讓使用者加入自訂參數值，而此參數值將在建立專案時加入至原始程式碼。主要的步驟一一詳述如下。
若要建立自訂範本精靈
建立實作 IWizard 介面的組件。
將組件安裝到全域組件快取。
建立專案並使用 [匯出範本] 精靈，從專案建立範本。
在 .vstemplate 檔案中加入 WizardExtension 項目以修改範本，使範本連結至實作 IWizard 的組件。
使用自訂精靈建立新專案。
實作 IWizard
處理過程中的第一個步驟是建立實作 IWizard 的組件。這個組件會使用 RunStarted 方法顯示 Windows Form，以便讓使用者加入在建立專案時將使用到的自訂參數值。
.gif "注意事項") 注意事項： |
|---|
這個範例會使用 Visual C# 來實作 IWizard，不過您也可以使用 Visual J# 或 Visual Basic。 |
若要實作 IWizard
這個範例包含兩個程式碼檔案：IWizardImplementation 是實作 IWizard 介面的類別，而 UserInputForm 是讓使用者輸入的 Windows Form。
IWizardImplementation 類別
IWizardImplementation 類別包含 IWizard 的每個成員的方法實作。在這個範例中，只有 RunStarted 方法會執行工作。其他所有方法不執行任何工作，或是只傳回 true。
RunStarted 方法接受四個參數：
Dictionary<TKey, TValue> 參數，包含範本中所有預先定義的參數集合。如需範本參數的詳細資訊，請參閱樣板參數。
WizardRunKind 參數，包含所使用的範本的相關資訊。
Object 陣列，包含由 Visual Studio 傳遞給精靈的參數集合。
這個範例會從使用者輸入表單中，將參數值加入 Dictionary<TKey, TValue> 參數。專案中 $custommessage$ 參數的每個執行個體將以使用者輸入的文字取代。
using System;
using System.Collections.Generic;
using Microsoft.VisualStudio.TemplateWizard;
using System.Windows.Forms;
using EnvDTE;
namespace CustomWizard
{
public class IWizardImplementation: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 = inputForm.get_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;
}
}
}
使用者輸入表單
使用者輸入表單會提供一個輸入自訂參數的簡單表單。表單中包含名為 textBox1 的文字方塊，以及名為 button1 的按鈕。當按一下按鈕時，來自文字方塊的文字便會儲存在 customMessage 參數中。
若要將 Windows Form 加入方案
在 [專案] 功能表上按一下 [加入新項目]。
按一下 [Windows Form]，將檔案命名為 UserInputForm.cs，然後按一下 [確定]。
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
namespace CustomWizard
{
public partial class UserInputForm : Form
{
private string customMessage;
public UserInputForm()
{
InitializeComponent();
}
public string get_CustomMessage()
{
return customMessage;
}
private void button1_Click(object sender, EventArgs e)
{
customMessage = textBox1.Text;
this.Dispose();
}
}
}
將組件安裝到全域組件快取
實作 IWizard 的組件必須以強式名稱簽署，並安裝到全域組件快取。
若要將組件安裝到全域組件快取中
使用強式名稱簽署組件。如需詳細資訊，請參閱 HOW TO：使用強式名稱簽署組件或HOW TO：簽署組件 (Visual Studio)。
將強式名稱的組件安裝到全域組件快取中。如需詳細資訊，請參閱 HOW TO：將組件安裝到全域組件快取。
建立要當做範本使用的專案
在這個範本中，當做範本使用的專案是一個主控台應用程式，它會顯示在自訂精靈的使用者輸入表單中所指定的訊息。
若要建立範本專案
建立新的 Visual C# 主控台應用程式。
在應用程式的 Main 方法中，加入下列程式碼行。
Console.WriteLine("$custommessage$");當從範本建立專案時，$custommessage$ 參數會以使用者輸入表單中所輸入的文字取代。
按一下 [檔案] 功能表上的 [匯出範本]。
在 [匯出範本] 精靈中，按一下 [專案範本]，選取正確的專案，然後按一下 [下一步]。
在 [匯出範本] 精靈中，輸入關於範本的描述性資訊，選取 [自動將範本匯入 Visual Studio] 核取方塊，然後按一下 [完成]。
範本現在會顯示在 [新增專案] 對話方塊中，但是不會使用自訂精靈。
下列範例會顯示匯出成範本之前的完整程式碼檔。
using System;
using System.Collections.Generic;
using System.Text;
namespace TemplateProject
{
class WriteMessage
{
static void Main(string[] args)
{
Console.WriteLine("$custommessage$");
}
}
}
修改範本
現在範本已經建立並顯示在 [新增專案] 對話方塊中，您必須加以修改，讓它使用您在前面的步驟中所建立的組件。
若要將自訂精靈加入範本
尋找包含範本的 .zip 檔。
在 [工具] 功能表上按一下 [選項]。
按一下 [專案和方案]。
閱讀 [Visual Studio 使用者專案範本位置] 文字方塊。如需詳細資訊，請參閱選項對話方塊、專案和方案、一般。
依據預設，這個位置為 My Documents\Visual Studio 2008\Templates\ProjectTemplates。
解壓縮這個 .zip 檔。
在 Visual Studio 中開啟 .vstemplate 檔。
在 TemplateContent 項目後面，加入 WizardExtension 項目 (Visual Studio 範本) 項目及自訂精靈組件的強式名稱。如需尋找組件的強式名稱的詳細資訊，請參閱 HOW TO：檢視全域組件快取的內容和 HOW TO：參考強式名稱簽署組件。
下列範例會顯示 WizardExtension 項目。
<WizardExtension> <Assembly>CustomWizard, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=fa3902f409bb6a3b</Assembly> <FullClassName>CustomWizard.IWizardImplementation</FullClassName> </WizardExtension>
使用自訂精靈
現在您可以從範本建立專案，並使用自訂精靈。
若要使用自訂精靈
在 [檔案] 功能表上，按一下 [新增專案]。
在 [新增專案] 對話方塊中，找出您的範本，並輸入名稱，然後按一下 [確定]。
精靈使用者輸入表單便會開啟。
輸入自訂參數的值，然後按一下按鈕。
精靈使用者輸入表單便會關閉，同時會從範本建立專案。
在 [方案總管] 中，在原始程式碼檔上按一下滑鼠右鍵，並按一下 [檢視程式碼]。
請注意，$custommessage$ 會以在精靈使用者輸入表單中所輸入的文字取代。
請參閱
參考
WizardExtension 項目 (Visual Studio 範本)