Visual Studio DSL 入門 14：使用 WiX 製作 DSL 設計器安裝程式

前言

前幾節已完成狀態機設計器的建模、驗證、程式碼生成，但皆在實驗性偵錯專案中執行。若要將設計器部署至僅安裝 Visual Studio (未安裝 SDK) 的機器，必須製作安裝程式。本節示範使用 VS.NET 內建的 Domain Specific Language Setup 專案 (基於 WiX) 產出安裝檔。

步驟 1：新增 DSL 安裝專案

1. 方案總管右鍵 > 加入 > 新專案。
2. 專案類型選擇 Extensibility > Domain Specific Language Setup。

步驟 2：理解自動產生的安裝定義與 WiX 檔案

專案建立後會自動參考 Dsl 與 DslPackage 專案，並依據其中繼資料產生 InstallerDefinition.dslsetup：

<installerDefinition xmlns="https://schemas.microsoft.com/VisualStudio/2005/DslTools/InstallerDefinitionModel"
    productUrl="InsertProductUrlHere"
    defaultDirectoryName="LanguageSm"
    productVersion="1.0.0"
    requiresCSharp="true"
    requiresVisualBasic="true"
    productCode="326b807c-a6da-43ac-9d29-f75cf060622a"
    upgradeCode="cc04b782-48c3-49c5-a60e-eda39258bfaa"
    localeId="1033">
  <dslPackage name="LanguageSm" project="DslPackage" assemblyPath="Company.LanguageSm.DslPackage.dll" registryRoot="SOFTWARE\Microsoft\VisualStudio\9.0">
    <fileExtensions>
      <fileExtension name="mydsl5" extension="mydsl5" descriptionKey="FileDescription" hasIcon="true" iconId="0"/>
    </fileExtensions>
    <supportingAssemblies>
      <supportingAssembly name="Dsl" project="Dsl" assemblyPath="Company.LanguageSm.Dsl.dll"/>
    </supportingAssemblies>
  </dslPackage>
  <licenseAgreement filePath="Files\EULA.rtf" isEmbedded="true" />
  <supportingFiles>
    <supportingFile name="Readme" filePath="Files\Readme.htm" installShortcut="true" shortcutIconPath="Resources\ReadmeShortcut.ico" openAfterInstall="true"/>
  </supportingFiles>
  <vsItemTemplates>
    <vsItemTemplate localeId="1033" targetDirectories="CSharp" project="DslPackage" templatePath="CSharp\1033\LanguageSm.zip"/>
    <vsItemTemplate localeId="1033" targetDirectories="VisualBasic" project="DslPackage" templatePath="VisualBasic\1033\LanguageSm.zip"/>
  </vsItemTemplates>
  <dslSchemas>
    <dslSchema project="Dsl" filePath="GeneratedCode\LanguageSmSchema.xsd"/>
  </dslSchemas>
</installerDefinition>

關鍵節點說明

• installerDefinition (根節點)：全域設定——產品 URL、目錄名稱、版本、是否需 C#/VB、產品代碼/升級代碼、地區碼 (1033=英文，中文可改 2052)。建議將 requiresVisualBasic 設為 false。
• dslPackage：DSL 封裝註冊資訊，來源為 DslDefinition.dsl，此處可微調。
• licenseAgreement：安裝時顯示的授權條款 (RTF)。
• supportingFiles：需複製至安裝目錄的附加檔案 (如 Readme)。
• vsItemTemplates：專案項目範本 (「加入新項目」時出現)，非程式碼生成 T4 範本。localeId 依 VS 語言版本調整。

專案下會產生多個 .wxs (WiX 原始檔) 與對應 .tt (T4 範本)：

• Main.wxs：主安裝腳本，參考其他片段。
• Files.wxs：安裝目錄結構與檔案 (DLL、附屬檔)。
• Registry.wxs：登錄項目寫入。
• UI.wxs：安裝介面。
• Strings.wxs：本地化字串表 (多語言可新增 Strings_zh-cn.wxs 等)。

步驟 3：重新產生範本並建置安裝專案

1. 方案總管工具列點擊「轉換所有範本」。
2. 建置 DSL Setup 專案，輸出訊息顯示呼叫 SDK 附帶的 WiX candle.exe、light.exe 編譯連結：

candle.exe -dConfiguration=Debug -out obj\Debug\ -w0 -v Files.wxs Registry.wxs Main.wxs UI.wxs
light.exe -b ... -loc Strings.wxl -out bin\Debug\LanguageSm.msi -sa -w0 -v obj\Debug\Files.wixobj ...

3. 建置完成後，bin\Debug 下可找到 LanguageSm.msi (或 .exe)，雙擊安裝。

安裝畫面

完成後，在 Visual Studio 新增專案項目時即可看到 LanguageSm 範本：

步驟 4：關鍵——套用 Package Load Key (PLK) 讓未安裝 SDK 的機器也能載入

若直接將上述 MSI 部署至未安裝 VS SDK 的機器，設計器無法載入。必須取得 PLK 並嵌入封裝：

1. 登入 VSX 網站 https://msdn.microsoft.com/zh-cn/vsx/cc655795(en-us).aspx，填寫資訊 (來源於 DslDefinition.dsl 根節點屬性) 產生 PLK。
2. 
3. 開啟 DslPackage 專案 VSPackage.resx，新增字串資源：名稱 = 1，值 = 產生的 PLK GUID。
   
4. 開啟 DslPackage\GeneratedCode\Package.tt，取消註解 [ProvideLoadKey] 屬性：
   /// [VSShell::ProvideLoadKey("Standard", Constants.ProductVersion, Constants.ProductName, Constants.CompanyName, 1)]
5. 儲存、重新轉換所有範本、重新建置 DSL Setup 專案產出新 MSI。

此 MSI 即可在未安裝 SDK 的機器直接安裝使用。

步驟 5：DSL Setup 專案的限制與替代方案

• WiX + T4 雖簡單但彈性有限：特殊需求 (自訂安裝動作、複雜 UI 流程) 難以滿足，除非放棄 T4 直接撰寫 WiX。
• 可完全不使用 DSL Setup 專案：改用一般安裝專案、InstallShield、或手寫 WiX，自行處理登錄、檔案複製、多語言、UI 流程。
• VS 2010 起已改用 VSIX 擴充管理器：不再使用 WiX，部署更簡單。

程式碼下載

LanguageSm6.rar