# NavisworksTransport 插件 MSI 安装包制作指南

## 概述

本指南详细说明如何使用 Visual Studio Installer Projects 为 NavisworksTransport 2026 物流路径规划插件创建 MSI 安装包。

### 环境要求

- **Visual Studio**: 2019/2022（推荐2022）
- **操作系统**: Windows 10/11
- **目标框架**: .NET Framework 4.8
- **插件平台**: Navisworks Manage 2026
- **架构**: x64

---

## 第一部分：安装 Visual Studio Installer Projects

### 步骤 1：安装扩展

1. 打开 Visual Studio 2022
2. 点击菜单：`扩展` → `管理扩展`
3. 在搜索框中输入：**Microsoft Visual Studio Installer Projects**
4. 点击 `下载` 并重启 Visual Studio

> **注意**: 如果扩展不可用，可以从 Visual Studio Marketplace 下载 VSIX 文件手动安装

### 验证安装

重启后，在 `创建新项目` 中搜索 "Setup"，应该能看到：

- Setup Project
- Web Setup Project
- Merge Module Project

---

## 第二部分：创建安装项目

### 步骤 1：添加到现有解决方案

1. 在 Visual Studio 中打开 NavisworksTransport 解决方案
2. 右键点击解决方案 → `添加` → `新建项目`
3. 在项目类型中搜索 "Setup" 或展开：
   - `其他项目类型` → `安装和部署` → `Visual Studio Installer`
4. 选择 `Setup Project`，命名为：`NavisworksTransport.Setup`
5. 点击 `添加`

### 步骤 2：配置项目属性

#### 注意事项

由于Visual Studio和Installer Projects插件版本差异，某些图形界面设置方法可能不可用或显示不完整。因此，推荐使用以下最可靠的配置方法：

#### 手动编辑vdproj文件（唯一可靠方法）

直接编辑项目文件是最可靠的配置方式，适用于所有Visual Studio版本：

1. 在解决方案资源管理器中选中 `NavisworksTransport.Setup` 项目
2. 点击菜单栏 `项目` → `卸载项目`
3. 再次右键点击项目 → `编辑 NavisworksTransport.Setup.vdproj`
4. 在打开的文件中找到 `"Product"` 节点（通常在文件末尾附近）
5. 直接修改以下属性值：

```ini
"ProductName" = "8:NavisworksTransport 2026"
"Manufacturer" = "8:YourCompany"
"ProductVersion" = "8:1.0.0"
"Title" = "8:NavisworksTransport Setup"
"Subject" = "8:Navisworks 2026 物流路径规划插件"
```

#### 高级设置说明

如需配置构建事件、系统必备项等高级设置，请参考Visual Studio Installer Projects的官方文档，或根据实际需要在vdproj文件中查找并修改对应节点的属性值。

> **升级代码**: 首次安装后会生成 `UpgradeCode`，**升级时保持不变**，版本号变更会触发自动升级

---

## 第三部分：添加项目输出和文件

### 方案 A：通过文件系统编辑器（推荐）

#### 步骤 1：打开文件系统编辑器

右键点击安装项目 → `视图` → `文件系统`

#### 步骤 2：配置 Application Folder（应用程序文件夹）

1. 点击左侧的 `Application Folder`
2. 右侧右键 → `添加` → `项目输出...`

#### 步骤 3：添加 Primary Output（主输出）

在 `添加项目输出组` 对话框中：

- 项目：`TransportPlugin`
- 选择配置：`Release`
- 平台：`x64`（**重要：必须与项目平台一致，否则会出现平台不兼容错误**）
- 输出类型：选择 `Primary output`
- 点击 `确定`

> **Primary Output 包含**: 主DLL、依赖DLL、PDB文件（Release模式下通常不包含PDB）

#### 步骤 4：添加内容文件（Content Files）

如果插件需要额外的配置文件：

1. 右键点击 `Application Folder`
2. `添加` → `文件...`
3. 手动添加需要的配置文件：

   - config.json（如果存在）
   - README.txt
   - 许可协议.txt
   - 其他资源文件

#### 步骤 5：配置输出属性

右键点击已添加的 `Primary output` → `属性窗口`

设置：

- `Condition`: （留空，表示始终安装）
- `Register`: NoRegister（插件无需注册）

#### 步骤 6：排除不必要的依赖DLL

**为什么需要排除？**

- 系统DLL（如System.Net.Http.dll、System.IO.Compression.dll等）由Windows系统提供
- Navisworks API DLL（如Autodesk.Navisworks.*.dll）由Navisworks应用程序提供
- 这些DLL不应包含在安装包中，避免版本冲突和安装包过大

**如何识别需要排除的DLL？**

- **系统DLL**：通常以`System.`开头，如System.Net.Http.dll、System.IO.Compression.dll
- **Navisworks API DLL**：以`Autodesk.Navisworks.`开头
- **其他应用程序DLL**：由其他已安装软件提供的DLL

**排除方法：**

1. **通过文件系统编辑器排除**
   - 在文件系统编辑器中，展开 `Application Folder` → `Primary output from TransportPlugin (Active)`
   - 找到需要排除的DLL（如System.Net.Http.dll）
   - 右键点击该DLL → `属性窗口`
   - 将 `Exclude` 属性设置为 `TRUE`

2. **通过直接编辑项目文件排除**（高级方法）
   - 在解决方案资源管理器中，右键点击setup项目 → `卸载项目`
   - 再次右键点击 → `编辑 NavisworksTransport.Setup.vdproj`
   - 找到需要排除的DLL节点（通常包含"AssemblyAsmDisplayName"、"Name"和"SourcePath"）
   - 将 `"Exclude" = "11:FALSE"` 修改为 `"Exclude" = "11:TRUE"`
   - 保存文件，右键点击项目 → `重新加载项目`

**需要排除的常见DLL：**

- 系统DLL：
  - System.Net.Http.dll
  - System.IO.Compression.dll
  - System.IO.Compression.FileSystem.dll
  - System.Diagnostics.Tracing.dll
  - System.Core.dll
  - System.Windows.Forms.dll
  - System.Drawing.dll
  - System.Data.dll
  - System.xml.dll

- Navisworks API DLL：
  - Autodesk.Navisworks.Api.dll
  - Autodesk.Navisworks.ComApi.dll
  - Autodesk.Navisworks.Interop.ComApi.dll
  - Autodesk.Navisworks.Controls.dll
  - Autodesk.Navisworks.Clash.dll
  - Autodesk.Navisworks.Timeliner.dll

**验证排除结果：**

1. 重新构建setup项目
2. 检查构建输出，确认排除的DLL不再被包含
3. 安装后检查目标目录，确认排除的DLL没有被安装
4. 启动Navisworks，验证插件正常运行（依赖项由系统或Navisworks提供）

---

## 第四部分：配置安装目录

### 默认安装位置

插件需要安装到 Navisworks 的插件目录：

默认路径: C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin\

### 设置方法

1. 在 `文件系统` 视图中
2. 点击左侧 `Application Folder`
3. 将AlwaysCreate属性设置为`TRUE`
4. 在属性窗口中设置 `DefaultLocation`：

DefaultLocation = [CommonAppDataFolder]\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin

### 目录结构说明

| 目录 | 说明 | 环境变量 | 正确的Windows Installer属性 |
|------|------|----------|----------------------------|
| 公共应用数据 | %ProgramData% | C:\ProgramData\ | [CommonAppDataFolder] |
| 程序文件目录 | %ProgramFiles% | C:\Program Files\ | [ProgramFilesFolder] |
| 用户应用数据 | %AppData% | C:\Users\用户名\AppData\Roaming\ | [AppDataFolder] |
| 本地用户应用数据 | %LocalAppData% | C:\Users\用户名\AppData\Local\ | [LocalAppDataFolder] |
| 桌面文件夹 | 桌面 | C:\Users\用户名\Desktop\ | [DesktopFolder] |
| 开始菜单 | 开始菜单 | C:\ProgramData\Microsoft\Windows\Start Menu\ | [StartMenuFolder] |

> **注意**: Windows Installer Projects 扩展使用 `[CommonAppDataFolder]` 来表示系统的 `%ProgramData%` 目录，而不是 `[ProgramDataFolder]`

---

## 第五部分：添加用户界面元素

### 步骤 1：打开用户界面编辑器

右键点击安装项目 → `视图` → `用户界面`

### 步骤 2：添加欢迎界面（可选）

1. 右键点击 `Install` → `添加对话框`
2. 选择 `Welcome` 对话框
3. 设置属性：
   - BannerBitmap: 选择横幅图片（可选）
   - CopyrightWarning: "本软件受版权保护"
   - WelcomeText: "欢迎安装 NavisworksTransport 2026"

---

## 第六部分：配置系统必备项

### 检查 .NET Framework 4.8

1. 右键点击安装项目 → `属性`
2. 点击 `系统必备...` 按钮
3. 在系统必备组件列表中：
   - ✅ 勾选 `Microsoft .NET Framework 4.8 (x86 and x64)`
4. 设置：
   - ✅ `下载系统必备组件从以下位置`: 组件供应商的网站

---

## 第七部分：构建和测试

### 构建 Release 版本

#### 方法一：通过 Visual Studio

1. 在配置管理器中设置：
   - 活动解决方案配置：`Release`
   - 活动解决方案平台：`x64`
2. 右键点击安装项目 → `生成`
3. 检查输出窗口确认无错误

#### 方法二：通过命令行

```batch
:: 构建解决方案
devenv NavisworksTransport.sln /build Release /project NavisworksTransport.Setup /projectconfig Release

:: 或使用 MSBuild
msbuild NavisworksTransport.sln /p:Configuration=Release /p:Platform=x64 /t:NavisworksTransport.Setup
```

### 构建输出

成功构建后，在以下位置找到安装文件：

- 解决方案目录\bin\Release\NavisworksTransport.Setup.msi
- 解决方案目录\bin\Release\setup.exe

### setup.exe与.msi文件的区别

Visual Studio Installer Projects 会生成两个安装文件，它们各有不同用途：

#### setup.exe（引导程序/启动器）

- **主要功能**：检查并安装系统必备组件（如特定版本的.NET Framework）
- **使用场景**：
  - 目标系统可能缺少必要的依赖项
  - 需要自动处理依赖安装的情况
  - 提供更友好的安装体验
- **工作机制**：
  1. 检查系统是否满足所有必备条件
  2. 如果缺少依赖，会自动下载并安装
  3. 然后启动.msi安装包完成实际安装

#### .msi文件（Windows Installer数据包）

- **主要功能**：包含实际的安装内容和配置
- **使用场景**：
  - 目标系统已经满足所有依赖条件
  - 需要通过命令行进行静默安装
  - 只需要实际安装内容，不需要依赖检查
- **工作机制**：
  - 直接通过Windows Installer服务安装
  - 可以使用msiexec命令进行高级安装配置
  - 不具备检查和安装系统必备组件的能力

#### 分发建议

- **完整分发**：同时提供setup.exe和.msi文件，让用户根据需求选择
- **简化分发**：如果可以确保所有目标系统都已安装必要的依赖项（如Navisworks 2026环境已包含所需的.NET Framework版本），可以只提供.msi文件

### 测试安装

1. **静默安装测试**:

   ```batch
   msiexec /i NavisworksTransport.Setup.msi /qn /l*v install.log
   ```

   - `/qn`: 无UI
   - `/l*v`: 详细日志

2. **卸载测试**:

   ```batch
   msiexec /x {ProductCode} /qn /l*v uninstall.log
   ```

   - `{ProductCode}`: 安装日志中的产品代码

3. **验证安装**:
   - 检查目录：`C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin\`
   - 确认文件存在：`TransportPlugin.dll`
   - 启动Navisworks 2026，检查插件是否加载

---

## 第九部分：高级配置

### 1. 版本升级管理

#### 第一次发布后

1. 记录生成的 `UpgradeCode`
2. 在项目属性中设置：
   - Version: 1.0.1（递增）
   - Keep UpgradeCode: 不变

#### 升级策略

- **小版本升级**（1.0.0 → 1.0.1）：
  - 版本号变更，UpgradeCode不变
  - 自动卸载旧版本，安装新版本

---

## 第十部分：自动化构建脚本

### 创建 `build-msi.bat`

在解决方案根目录创建批处理脚本：

```batch
@echo ===============================
@echo NavisworksTransport MSI构建脚本
@echo ===============================

@echo 正在清理旧文件...
if exist "bin\Release\*.msi" del /q "bin\Release\*.msi"
if exist "bin\Release\*.cab" del /q "bin\Release\*.cab"

@echo 正在构建解决方案（Release|x64）...
devenv NavisworksTransport.sln /build Release /project NavisworksTransport.Setup /projectconfig Release

@echo.
if exist "bin\Release\NavisworksTransport.Setup.msi" (
    echo ===============================
    echo ✅ MSI构建成功！
    echo 文件位置：bin\Release\NavisworksTransport.Setup.msi
    echo ===============================
    explorer "bin\Release"
) else (
    echo ❌ 构建失败，请检查错误信息
    exit /b 1
)

pause
```

### 创建 `deploy.bat`（自动部署到测试环境）

```batch
@echo ===============================
@echo 自动部署到测试环境
@echo ===============================

@echo 正在安装MSI...
msiexec /i "bin\Release\NavisworksTransport.Setup.msi" /qn /l*v "logs\install.log"

@echo 检查安装结果...
if exist "C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin\TransportPlugin.dll" (
    echo ✅ 部署成功！
) else (
    echo ❌ 部署失败，请检查安装日志：logs\install.log
)

pause
```

---

## 第十一部分：常见问题与解决

### Q1: 构建时提示"无法找到..."

**原因**: 依赖项路径错误或项目引用丢失

**解决**:

1. 检查项目引用：`TransportPlugin.csproj`
2. 确保所有NuGet包已还原
3. 清理解决方案：`Build` → `Clean Solution`
4. 重新构建：`Build` → `Rebuild Solution`

### Q2: MSI安装后插件不显示

**原因**:

- 文件安装到错误目录
- 缺少依赖DLL
- Navisworks 2026未启动或版本不匹配

**解决**:

1. 检查安装目录：

   C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin\

2. 检查Navisworks加载日志：

   %AppData%\Autodesk\Navisworks Manage 2026\Logs\*.log

3. 手动复制DLL到正确位置测试

### Q3: 卸载后残留文件

**原因**: 安装项目未配置清理旧文件

**解决**:

1. 创建自定义卸载操作删除残留文件

### Q4: .NET Framework 版本冲突

**现象**: 安装时提示".NET Framework版本不受支持"

**解决**:

1. 检查目标机器.NET版本：`dotnet --list-runtimes`
2. 在安装项目中明确指定.NET 4.8
3. 在系统必备组件中勾选.NET 4.8

### Q5: 平台不兼容错误

**现象**: 构建时出现 "File 'xxx.dll' targeting 'AMD64' is not compatible with the project's target platform 'x86'" 错误

**解决**:

1. 在解决方案资源管理器中右键点击 `解决方案 'NavisworksTransport'` → `配置管理器`
2. 将 `NavisworksTransport.Setup` 项目的平台设置为 `x64`
3. 确保所有项目的平台一致（都是x64）
4. 在添加项目输出时，确保选择的平台是 `x64`

### Q6: 权限不足错误

**现象**: 安装时提示"拒绝访问"

**解决**:

1. 右键点击MSI → `以管理员身份运行`
2. 或在批处理中自动提权：

   ```batch
   msiexec /i NavisworksTransport.Setup.msi /qn
   ```

   > UAC会自动提示

### Q7: MSI安装后，deploy-plugin.bat 开发部署提示"拒绝访问"且必须弹UAC

**背景**：MSI 安装的 DLL 是**管理员所有**，对 `BUILTIN\Users` 只有只读权限（甚至禁用继承）。
因此用开发部署脚本 `deploy-plugin.bat`（普通用户）覆盖这些 DLL 时会被拒绝，必须提权弹 UAC。

**症状**：
- 复制 `TransportPlugin.dll` 报 "Access to the path ... is denied"
- 即使 Navisworks 未运行（文件未锁）也无法覆盖
- 目标 DLL 的 ACL 为：
  ```
  SYSTEM: FullControl
  BUILTIN\Administrators: FullControl
  BUILTIN\Users: ReadAndExecute   ← 普通用户无法写
  ```

**根因**：MSI 安装创建的管理员文件对普通用户只读。卸载 MSI 也常不彻底，
会残留共享依赖 DLL（如 `System.Data.SQLite.dll`）继续阻塞部署。

**解决（一次性管理员修复权限）**：以管理员给整个目标目录及所有文件授予
`BUILTIN\Users FullControl`，并解除继承保护。之后所有文件用户可写，免 UAC 部署。

```powershell
# 管理员 PowerShell 中执行一次
$d = "C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\TransportPlugin"
$rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
    "BUILTIN\Users", "FullControl",
    "ContainerInherit,ObjectInherit", "None", "Allow")
$acl = Get-Acl $d
$acl.SetAccessRule($rule)
$acl.SetAccessRuleProtection($false, $true)   # 解除继承保护，让现有文件继承
Set-Acl $d $acl
Get-ChildItem $d -File -Recurse | ForEach-Object {
    $fa = Get-Acl $_.FullName
    $fa.SetAccessRule($rule)
    $fa.SetAccessRuleProtection($false, $true)
    Set-Acl $_.FullName $fa
}
```

**备选方案**：

1. 用 MSI 卸载程序彻底卸载插件（清理残留），再让 `deploy-plugin.bat` 全新部署
2. 每次部署都批准一次 UAC（MSI 与开发部署共存时最简单）
3. `deploy-plugin.bat` 已在部署成功后给目标文件设置 `BUILTIN\Users FullControl`，
   若文件被重新弄成管理员所有，下次部署会自动修复（仍需一次性管理员触发）

> **建议**：MSI 与 `deploy-plugin.bat` 部署到同一目录是互相覆盖的关系。
> 请决定主部署方式——若用 MSI 分发，开发调试用 `deploy-plugin.bat` 时建议先修好权限。

---

## 第十二部分：最佳实践

### 1. 项目组织

NavisworksTransport/
├── TransportPlugin.sln
├── TransportPlugin/         # 插件项目
├── NavisworksTransport.Setup/         # 安装项目
├── doc/design/2026/
│   └── MSI_Installation_Guide.md
├── scripts/
│   ├── build-msi.bat
│   └── deploy.bat
├── installer/
│   └── assets/                         # 图标、许可协议等
└── README.md

### 2. 版本命名规范

采用 `Semantic Versioning`（语义化版本）：

- **Major.Minor.Patch.Build**
- 示例：`1.0.0.0` → `1.0.1.0` → `1.1.0.0`

### 3. 构建配置

| 配置 | 用途 | 输出 |
|------|------|------|
| Debug | 开发测试 | 包含PDB，日志详细 |
| Release | 发布版本 | 优化，体积小 |
| CI/CD | 自动化构建 | 静默构建，生成MSI |

### 4. 依赖管理最佳实践

**排除不必要的DLL：**

- 始终排除**系统DLL**（如System.*.dll）
- 始终排除**Navisworks API DLL**（Autodesk.Navisworks.*.dll）
- 排除**其他应用程序提供的DLL**（如第三方软件的共享DLL）

**仅包含必要的文件：**

- 自定义应用程序DLL（TransportPlugin.dll）
- 第三方库DLL（如SQLite.NET.dll等）
- 配置文件（config.json等）
- 资源文件（图标、文档等）

**定期检查：**

- 每次构建后检查输出目录的文件列表
- 确保没有包含不需要的DLL
- 检查新添加的依赖项，确认是否需要排除

### 4. 测试清单

安装MSI前必须测试：

- [ ] 清理旧的Navisworks插件目录
- [ ] 检查目标机器.NET 4.8已安装
- [ ] 检查Navisworks 2026已安装
- [ ] 以管理员权限运行安装
- [ ] 安装后启动Navisworks验证插件加载
- [ ] 测试插件核心功能
- [ ] 卸载并验证清理干净

### 5. 发布前检查

- [ ] 版本号正确
- [ ] 所有依赖DLL包含
- [ ] XAML文件已嵌入DLL（无需单独安装）
- [ ] 第三方许可证包含（如要求）
- [ ] MSI大小合理（通常 < 10MB）

---

## 第十三部分：参考链接

### 官方文档

- [Visual Studio Installer Projects 文档](https://docs.microsoft.com/en-us/visualstudio/deployment/installer-projects?view=vs-2022)
- [WiX Toolset 文档](https://wixtoolset.org/)
- [MSDN: Windows Installer](https://docs.microsoft.com/en-us/windows/win32/msi/)

### 工具下载

- [Visual Studio Installer Projects 扩展](https://marketplace.visualstudio.com/items?itemName=visualstudioclient.MicrosoftVisualStudio2017InstallerProjects)
- [Advanced Installer](https://www.advancedinstaller.com/)
- [WiX Toolset](https://wixtoolset.org/releases/)

### Navisworks 插件开发

- [Navisworks Developer Center](https://www.autodesk.com/developer-network/platform-technologies/navisworks)
- [Navisworks API 参考](https://www.autodesk.com/developer-network/platform-technologies/navisworks/api-reference)

---

## 附录：完整示例配置

### 项目文件结构（简化）

NavisworksTransport.Setup/
├── 文件系统编辑器
│   ├── Application Folder/
│   │   ├── Primary output from TransportPlugin (Active)
│   │   └── license.txt
└── 系统必备组件
    ├── Microsoft .NET Framework 4.8 (x86 and x64)
    └── Windows Installer 4.5

### MSI 属性完整配置

| 属性 | 示例值 | 说明 |
|------|--------|-----|
| AddRemoveProgramsIcon | setup.ico | 控制面板图标 |
| Author | YourCompany | 作者 |
| Description | Navisworks 2026 物流路径规划插件 | 描述 |
| InstallAllUsers | True | 允许多用户安装 |
| Manufacturer | YourCompany | 制造商 |
| PostBuildEvent | copy *.msi ..\..\bin\Release\ | 后构建事件 |
| ProductCode | {GUID} | 产品代码（自动生成） |
| ProductName | NavisworksTransport 2026 | 产品名称 |
| SearchPath | $(ProjectDir) | 搜索路径 |
| Subject | 物流路径规划插件 | 主题 |
| Title | NavisworksTransport Setup | 标题 |
| UpgradeCode | {GUID} | 升级代码（首次手动设置） |
| Version | 1.0.0.0 | 版本号 |

---

**文档版本**: 1.0
**最后更新**: 2025-11-18
**维护者**: NavisworksTransport 开发团队
