增加MSI安装程序生成指南,修改README.md

This commit is contained in:
tian 2025-11-17 12:49:35 +08:00
parent 5e1e4b04b2
commit fee00dfb82
2 changed files with 533 additions and 18 deletions

View File

@ -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 中创建基于这些路径点的对象动画
- 插件自动配置并运行一个链接到该动画的动态碰撞测试
- 当检测到碰撞时,插件将通过颜色覆盖直观地高亮显示碰撞的物体,并弹出明确的提示信息
- 当检测到碰撞时,插件将通过颜色覆盖直观地高亮显示碰撞的物体,并弹出明确的提示信息

View File

@ -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 开发团队