Visual Studio 安裝項目完整教程：自定義對話框配置連接字串與自定義動作

場景：WinForm/WPF 專案需打包安裝，安裝時讓用戶輸入資料庫連接資訊並自動寫入 App.config

Visual Studio 內建「安裝專案」雖老舊但零依賴、無需學習 WiX/NSIS 腳本，適合中小型桌面應用快速交付。本文以「安裝時輸入 SQL Server 連接參數 → 自定義動作修改 WinUI.exe.config」為例，完整演示從建立專案到生成 MSI 的全流程。

步驟 1：準備專案與 App.config

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="ConnectionString" connectionString="" providerName="System.Data.SqlClient" />
  </connectionStrings>
</configuration>

關鍵：connectionString 預留空值，安裝時由自定義動作填入。

步驟 2：新增安裝專案並包含輸出

1. 方案右鍵 → 新增專案 → 「安裝專案」 → 命名 SetupProject。
2. 右鍵安裝專案 → 加入 → 專案輸出 → 選擇主專案（WinUI）、業務邏輯層、資料層等所有「主要輸出」。

步驟 3：建立桌面捷徑

1. 檢視 → 檔案系統 → 左側選「用戶的桌面」 → 右鍵「建立新捷徑」。
2. 選擇「應用程式資料夾」下的主輸出 → 確定 → 重命名為友好名稱。

步驟 4：自定義安裝介面（用戶輸入對話框）

1. 檢視 → 使用者介面 → 右鍵「開始」 → 加入對話方塊 → 選「文字方塊 (A)」→ 上移至「安裝資料夾」之前。
2. 屬性視窗設定：

步驟 5：建立自定義動作類別庫

1. 方案新增「類別庫」專案 → 命名 CustomActions。
2. 加入參考：System.Configuration.Install、System.Configuration、System.Xml。
3. 新增類 SetSqlConnection.cs 繼承 Installer 並標記 [RunInstaller(true)]。

步驟 6：自定義動作核心代碼

using System;
using System.Collections;
using System.ComponentModel;
using System.Configuration.Install;
using System.Xml;
using System.IO;

namespace CustomActions {
    [RunInstaller(true)]
    public partial class SetSqlConnection : Installer {
        public SetSqlConnection() { InitializeComponent(); }

        public override void Install(IDictionary stateSaver) {
            base.Install(stateSaver);

            // 從 CustomActionData 取得用戶輸入
            string server = Context.Parameters["SqlServerIP"];
            string db = Context.Parameters["DataBase"];
            string user = Context.Parameters["UserName"];
            string pwd = Context.Parameters["Password"];
            string targetDir = Context.Parameters["TargetDir"]; // 結尾含反斜線

            // 組裝連接字串
            string connStr = $"Data Source={server};Initial Catalog={db};User ID={user};Password={pwd};Persist Security Info=True";

            // 修改目標目錄下的 WinUI.exe.config
            string configPath = Path.Combine(targetDir, "WinUI.exe.config");
            UpdateConnectionString(configPath, "ConnectionString", connStr);
        }

        public static void UpdateConnectionString(string configPath, string name, string connStr) {
            XmlDocument doc = new XmlDocument();
            doc.Load(configPath);
            XmlNode node = doc.SelectSingleNode($"configuration/connectionStrings/add[@name='{name}']");
            if (node != null) {
                node.Attributes["connectionString"].InnerText = connStr;
                doc.Save(configPath);
            }
        }

        public override void Uninstall(IDictionary savedState) { base.Uninstall(savedState); }
        public override void Commit(IDictionary savedState) { base.Commit(savedState); }
        public override void Rollback(IDictionary savedState) { base.Rollback(savedState); }
    }
}

步驟 7：註冊自定義動作並傳遞參數

1. 檢視 → 自定義動作 → 右鍵「安裝」 → 加入自定義動作 → 選「應用程式資料夾」 → 選 CustomActions 專案主輸出。
2. 選中新增的自定義動作，屬性視窗設定 CustomActionData：

/SqlServerIP=[SQLSERVER_NAME] /DataBase=[DATABASE_NAME] /UserName=[USERNAME] /Password=[PASSWORD] /TargetDir="[TARGETDIR]\"

注意：中括號內為步驟 4 定義的 EditXProperty 值；[TARGETDIR] 為安裝目錄，末尾必須加反斜線並用雙引號包裹，防止路徑含空格截斷。

步驟 8：建置與驗證

1. 建置安裝專案 → 輸出 SetupProject.msi。
2. 雙擊安裝 → 出現自定義對話框輸入連接資訊 → 完成。
3. 檢查安裝目錄 WinUI.exe.config：

<add name="ConnectionString" connectionString="Data Source=DBServer;Initial Catalog=szitrDB;User ID=szitr.com;Password=szitr.com;Persist Security Info=True" providerName="System.Data.SqlClient" />

常見坑與解決方案

進階擴展

• 安裝時建立資料庫：在 Install 中執行 SqlConnection + CREATE DATABASE 腳本，失敗時拋出 InstallException 觸發回滾。
• 多組態支援：對話框新增「環境」下拉框（開發/測試/生產），自定義動作根據選擇寫入不同 connectionStrings 節點。
• 修補程式 (MSP)：後續版本只需更新檔案，產生 Patch 包，用戶無需重裝。

總結

VS 安裝專案雖非主流，但「零學習成本、整合 IDE、支援自定義 UI 與動作」對中小團隊極具性價比。掌握 對話框屬性 → CustomActionData → Installer.Context.Parameters → XML 修改 Config 這條鏈路，即可解決 90% 桌面應用「安裝時配置」需求。若專案後期需支援自動更新、差分補丁、多語言、權限提升等高階場景，再遷移至 WiX Toolset 或 NSIS 不遲。