From fee00dfb8241dd0e4a2214fde7c5dca9b4ef1146 Mon Sep 17 00:00:00 2001
From: tian <11429339@qq.com>
Date: Mon, 17 Nov 2025 12:49:35 +0800
Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0MSI=E5=AE=89=E8=A3=85?=
 =?UTF-8?q?=E7=A8=8B=E5=BA=8F=E7=94=9F=E6=88=90=E6=8C=87=E5=8D=97=EF=BC=8C?=
 =?UTF-8?q?=E4=BF=AE=E6=94=B9README.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                                 |  32 +-
 doc/design/2026/MSI_Installation_Guide.md | 519 ++++++++++++++++++++++
 2 files changed, 533 insertions(+), 18 deletions(-)
 create mode 100644 doc/design/2026/MSI_Installation_Guide.md

diff --git a/README.md b/README.md
index 6e71efa..a37217d 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,22 @@
 # NavisworksTransport
 
-Navisworks 2017运输冲突检测插件，专用于物流路径规划。
+Navisworks2026运输冲突检测插件，专用于物流路径规划。
 
 ## 功能特性
 
-### 已实现功能（第一阶段）
-- ✅ **类别属性分配**：为模型项目添加物流类别属性（门、电梯、楼梯、通道、障碍物）
-- ✅ **批量处理**：支持同时为多个选中项目设置属性
-- ✅ **用户友好界面**：简洁的按钮式对话框
-- ✅ **COM API集成**：使用Navisworks COM API确保属性正确添加
-
-### 计划功能（后续阶段）
-- 🔄 模型分层转换和可见性控制
-- 🔄 导航地图构建
-- 🔄 A*路径规划算法
-- 🔄 动态碰撞检测
-- 🔄 动画和时间线集成
-- 🔄 DELMIA数据导出
+- ✅ 类别属性分配：为模型项目添加物流类别属性（门、电梯、楼梯、通道、障碍物）
+- ✅ 模型分层转换和可见性控制
+- ✅ 导航地图构建
+- ✅ A*路径规划算法
+- ✅ 动态碰撞检测
+- ✅ 动画和时间线集成
+- ✅ DELMIA数据导出
 
 ## 系统要求
 
-- Windows 7 或更高版本
-- Navisworks Manage 2017
-- .NET Framework 4.6.2
+- Windows 10 或更高版本
+- Navisworks Manage 2026
+- .NET Framework 4.8
 
 ## 安装说明
 
@@ -60,6 +54,7 @@ NavisworksTransportPlugin/
 ## 版本历史
 
 ### v1.0 (2025-01-11)
+
 - 实现基础的类别属性分配功能
 - 支持5种预定义物流类别
 - 提供批量处理能力
@@ -70,9 +65,10 @@ NavisworksTransportPlugin/
 本插件旨在简化 Navisworks Manage 中移动模型沿确定路径进行物理碰撞或干涉检测的流程。通过自动化 Animator 动画创建、Clash Detective 碰撞测试配置与运行，并提供直观的图形化碰撞结果显示，本插件将大大提高工作效率，并为用户提供一个快速验证施工物流和设备移动可行性的工具。
 
 完整的目标功能包括：
+
 - 在 Navisworks Ribbon 界面添加自定义按钮
 - 用户选择一个要移动的模型
 - 用户通过选择一系列模型元素来定义非直线路径点
 - 插件自动在 Animator 中创建基于这些路径点的对象动画
 - 插件自动配置并运行一个链接到该动画的动态碰撞测试
-- 当检测到碰撞时，插件将通过颜色覆盖直观地高亮显示碰撞的物体，并弹出明确的提示信息
\ No newline at end of file
+- 当检测到碰撞时，插件将通过颜色覆盖直观地高亮显示碰撞的物体，并弹出明确的提示信息
diff --git a/doc/design/2026/MSI_Installation_Guide.md b/doc/design/2026/MSI_Installation_Guide.md
new file mode 100644
index 0000000..d47e6c8
--- /dev/null
+++ b/doc/design/2026/MSI_Installation_Guide.md
@@ -0,0 +1,519 @@
+# 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：配置项目属性
+
+在解决方案资源管理器中右键点击 `NavisworksTransport.Setup` → `属性`
+
+| 属性名 | 值 | 说明 |
+|--------|-----|-----|
+| ProductName | NavisworksTransport 2026 | 产品名称 |
+| Manufacturer | YourCompany | 制造商 |
+| Version | 1.0.0 | 版本号 |
+| Title | NavisworksTransport Setup | 安装程序标题 |
+| Subject | Navisworks 2026 物流路径规划插件 | 主题 |
+
+> **升级代码**: 首次安装后会生成 `UpgradeCode`，**升级时保持不变**，版本号变更会触发自动升级
+
+---
+
+## 第三部分：添加项目输出和文件
+
+### 方案 A：通过文件系统编辑器（推荐）
+
+#### 步骤 1：打开文件系统编辑器
+
+右键点击安装项目 → `视图` → `文件系统`
+
+#### 步骤 2：配置 Application Folder（应用程序文件夹）
+
+1. 点击左侧的 `Application Folder`
+2. 右侧右键 → `添加` → `项目输出...`
+
+#### 步骤 3：添加 Primary Output（主输出）
+
+在 `添加项目输出组` 对话框中：
+
+- 项目：`NavisworksTransportPlugin`
+- 选择配置：`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（插件无需注册）
+
+### 方案 B：通过文件视图
+
+另一种方法是使用 `View` → `文件` 直接操作：
+
+安装项目
+├── Application Folder/
+│   ├── Primary output from NavisworksTransportPlugin (Active)
+│   └── 额外配置文件（如果有）
+
+---
+
+## 第四部分：配置安装目录
+
+### 默认安装位置
+
+插件需要安装到 Navisworks 的插件目录：
+
+默认路径: C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\NavisworksTransportPlugin\
+
+### 设置方法
+
+1. 在 `文件系统` 视图中
+2. 点击左侧 `Application Folder`
+3. 在属性窗口中设置 `DefaultLocation`：
+
+DefaultLocation = [ProgramDataFolder]\Autodesk\Navisworks Manage 2026\plugins\NavisworksTransportPlugin
+
+### 目录结构说明
+
+| 目录 | 说明 | 环境变量 |
+|------|------|----------|
+| [ProgramDataFolder] | 公共应用数据 | %ProgramData% |
+| [ProgramFilesFolder] | 程序文件目录 | %ProgramFiles% |
+| [AppDataFolder] | 用户应用数据 | %AppData% |
+| [CommonAppDataFolder] | 公共应用数据 | %AllUsersProfile% |
+
+---
+
+## 第五部分：添加用户界面元素
+
+### 步骤 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)`
+   - ✅ 勾选 `Windows Installer 4.5`（通常已包含在系统中）
+4. 设置：
+   - ✅ `下载系统必备组件从以下位置`: 组件供应商的网站
+   - 或 `将系统必备组件组件下载到同一应用程序文件夹`
+
+---
+
+## 第七部分：配置构建事件
+
+### 预构建事件
+
+在安装项目属性中添加：
+
+#### 清理旧的构建文件
+
+```batch
+if exist "$(ProjectDir)bin\Release\*.msi" del /q "$(ProjectDir)bin\Release\*.msi"
+if exist "$(ProjectDir)bin\Release\*.cab" del /q "$(ProjectDir)bin\Release\*.cab"
+```
+
+### 后构建事件
+
+#### 自动复制MSI到输出目录
+
+```batch
+xcopy "$(ProjectDir)bin\Release\NavisworksTransport.Setup.msi" "$(SolutionDir)bin\Release\" /Y
+```
+
+### 构建事件配置方法
+
+1. 右键点击安装项目 → `属性`
+2. 在属性窗口中设置：
+   - **PreBuildEvent**: 输入预构建命令
+   - **PostBuildEvent**: 输入后构建命令
+   - **PostBuildEventCondition**: `On successful build` 或 `Always`
+
+---
+
+## 第八部分：构建和测试
+
+### 构建 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
+```
+
+### 构建输出
+
+成功构建后，在以下位置找到MSI文件：
+
+解决方案目录\bin\Release\NavisworksTransport.Setup.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\NavisworksTransportPlugin\`
+   - 确认文件存在：`NavisworksTransportPlugin.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\NavisworksTransportPlugin\NavisworksTransportPlugin.dll" (
+    echo ✅ 部署成功！
+) else (
+    echo ❌ 部署失败，请检查安装日志：logs\install.log
+)
+
+pause
+```
+
+---
+
+## 第十一部分：常见问题与解决
+
+### Q1: 构建时提示"无法找到..."
+
+**原因**: 依赖项路径错误或项目引用丢失
+
+**解决**:
+
+1. 检查项目引用：`NavisworksTransportPlugin.csproj`
+2. 确保所有NuGet包已还原
+3. 清理解决方案：`Build` → `Clean Solution`
+4. 重新构建：`Build` → `Rebuild Solution`
+
+### Q2: MSI安装后插件不显示
+
+**原因**:
+
+- 文件安装到错误目录
+- 缺少依赖DLL
+- Navisworks 2026未启动或版本不匹配
+
+**解决**:
+
+1. 检查安装目录：
+
+   C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\NavisworksTransportPlugin\
+
+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: 权限不足错误
+
+**现象**: 安装时提示"拒绝访问"
+
+**解决**:
+
+1. 右键点击MSI → `以管理员身份运行`
+2. 或在批处理中自动提权：
+
+   ```batch
+   msiexec /i NavisworksTransport.Setup.msi /qn
+   ```
+
+   > UAC会自动提示
+
+---
+
+## 第十二部分：最佳实践
+
+### 1. 项目组织
+
+NavisworksTransport/
+├── NavisworksTransportPlugin.sln
+├── NavisworksTransportPlugin/         # 插件项目
+├── 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. 测试清单
+
+安装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 NavisworksTransportPlugin (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-17
+**维护者**: NavisworksTransport 开发团队