简介面向ArcGIS Engine桌面应用开发者与部署维护人员这份资源聚焦应用程序打包部署难题系统讲解如何将ArcGIS Engine Runtime和.NET Framework 3.5 SP1正确打包进安装程序避免分发时因环境依赖缺失导致的运行失败。资源为单个docx格式技术文档压缩包仅2.24MB内容源于ESRI中国内部培训资料条理清晰、截图丰富可直接作为操作参考。目前已有650人学习下载。文档覆盖两条打包路径一条是基于Visual Studio 2008自带安装项目从新建Setup项目、添加主输出、创建快捷方式到排除Esri DLL的完整流程另一条是使用InstallShield将Runtime和.NET Framework与应用程序合并打包的详细操作包括项目助手向导、安装目录配置和快捷方式设计。同时针对打包过程中常见的两个问题给出了排查思路能帮助开发者避开Esri DLL重复打包、目标机器环境检测等陷阱大幅提升AE程序交付的完整性与成功率。1. 打包 arcGIS Engine 应用程序先搞清楚“你在打包什么”很多用 arcGIS Engine 做过二次开发的人第一次做部署包时都会有一个错觉把 bin 目录里的 exe 和 dll 拷到另一台机器上装个 .NET Framework双击就能跑。结果通常是双击后闪退或者直接弹“无法加载 DLL“arcgis版本相关组件””。这不是代码问题而是 arcGIS Engine 应用程序打包这件事从一开始就被理解窄了。你要打包的不是“你的程序”而是“你的程序 它依赖的 ArcObjects 运行时 许可授权 环境配置”四层内容的组合。多数人只打了第一层所以到目标机器上必然缺东西。这篇文章解决的就是这条完整链路开发机上哪些文件要带走、哪些文件不能带走、目标机器上的 arcGIS Engine Runtime 怎么装、许可怎么免交互地初始化、装完之后程序还是起不来时怎么定位。适合做桌面 GIS 工具或行业业务系统交付的开发者也适合做实施部署的人参考。下面直接进入依赖盘点这才是打包能不能成功的地基。2. 打包前先盘点依赖bin 目录里哪些 dll 必须随包走2.1 开发时引用的 arcgis 相关 dll是拷走还是引用运行时用 arcGIS Engine 开发的程序在 Visual Studio 里一定会引用一组 Esri 开头的程序集比如 ESRI.ArcGIS.System、ESRI.ArcGIS.Geometry、ESRI.ArcGIS.Carto、ESRI.ArcGIS.Controls 等。在开发机上这些 dll 来自安装 arcGIS Engine Developer Kit 时的安装目录默认在C:\Program Files (x86)\ArcGIS\DeveloperKit10.x\DotNet这类路径下。编译之后Visual Studio 会把这些引用复制到你的 bin 输出目录所以你的 exe 旁边会出现一堆 Esri.*.dll。这带来第一个打包决策点程序集到底是“随包携带”还是“依赖目标机器上的运行时”如果随包携带包体会变大但每台机器是自包含的只要目标机器上有对应的 arcGIS Engine Runtime 和许可程序集版本不会和机器上其他 GIS 软件冲突。如果依赖目标机器的运行时理论上只要目标机器装了 Runtime程序集可以从 GAC 或安装目录加载但这样做风险很高目标机器可能存在多个 arcGIS 版本.NET 程序集绑定策略一旦解析到错误版本程序会直接抛异常。我一般会选“随包携带程序集”也就是让 Visual Studio 把引用复制到本地。这样打包时只需要确定一件事这台目标机器上有足够版本的 Runtime且许可初始化成功。如果你用的是 10.2 开发却在只有 10.8 Runtime 的机器上部署程序照样起不来因为 ArcObjects 的底层原生组件版本对不上。2.2 开发机 bin 目录里哪些文件看起来像 arcGIS Engine 文件但绝对不能拷打开开发机的 bin 目录除了你自己的 exe、config 和一堆 Esri.*.dll还有三类文件要特别区分。第一类是ESRI.ArcGIS开头的若干个*.dll这是托管程序集可以拷走但要注意它们有“版本化”的特性。你开发时用的版本号比如 10.2和运行时不一定一致。如果你在部署时把 10.2 的托管 dll 拷给了装有 10.8 Runtime 的机器加载时 .NET 可能因为强名称版本不匹配直接拒绝加载。这时需要在 app.config 里做 bindingRedirect或者统一开发环境和 Runtime 版本。这个后面第五节再细说。第二类是项目引用里带ESRI.ArcGIS前缀但实际来自ArcGIS\Desktop或ArcGIS\Engine安装目录的组件例如ESRI.ArcGIS.3DAnalyst.dll、ESRI.ArcGIS.Geodatabase.dll这些是托管包装但它们底层调用的是非托管的ArcObjects原生库。这些原生库不在你的 bin 目录里而是装在 Runtime 安装目录中。所以那些 dll 拷走没有意义你又不可能把整个原生目录搬过去。第三类是许可相关文件比如软件授权文件或初始化许可的缓存文件它们一般不在 bin 目录中。如果发现开发机上有一个license相关的目录或文件那些是开发许可千万别顺手打进部署包。曾经有一个项目把开发机的ArcGIS\Engine许可配置目录整个塞进安装包导致目标机器上程序读取到一套已经过期的开发许可最后所有功能初始化失败排查了很久才发现问题。2.3 拿一张自查表把依赖项列全打包前找一个干净的虚拟机按下面的列表逐项核对能少踩很多坑依赖项随包带走还是目标机安装说明ESRI.ArcGIS.*.dll托管程序集随包带走让发布目录自包含避免 GAC 版本冲突ArcObjects 原生运行时库目标机安装只能通过 arcGIS Engine Runtime 安装程序提供.NET Framework目标机安装或随包检测安装包需检测版本缺失时引导安装arcGIS Engine Runtime目标机安装必须和开发版本主版本一致10.x 系列内部还建议同小版本许可License目标机配置单机许可文件或浮动许可服务器配置必须初始化数据和配置文件随包带走如 mxd、gdb、json 配置注意路径写相对路径其他第三方 dll如 GDAL、Newtonsoft.Json随包带走只要是工程引用的全部带上注意“目标机安装”这一列不是让用户手动点下一步而是安装包启动时用静默安装参数自动装。下一节就给出一个可以抄的脚本。3. 用 Inno Setup 做一个可复现的 arcGIS Engine 部署包3.1 为什么用 Inno Setup而不是 InstallShield 或手工拷贝给 arcGIS Engine 程序做安装包安装工具的选择直接影响后期维护成本。InstallShield 是商业软件功能全但脚本语法复杂出问题不好排WiX 学习曲线陡写一个带自定义操作的安装包要维护大量 XML手工拷贝脚本最灵活但没法给用户提供卸载入口和桌面快捷方式也不适合交付给非技术客户。Inno Setup 是免费软件脚本用 Pascal 风格语法支持静默安装、自定义安装目录、写注册表、安装后执行其他程序。更重要的是它支持在安装过程中调用另一个 exe 或 msi 并等待其完成这正好用来驱动 arcGIS Engine Runtime 的安装。所以下面用 Inno Setup 做示例因为它是这个场景下最容易多人维护的方案。3.2 最小可用的 iss 脚本模板下面这个脚本做了三件事把你的 bin 目录装到目标机的指定位置再静默安装 arcGIS Engine Runtime以 10.x 的安装介质为例最后留下一个 Start 菜单快捷方式。; arcgis_engine_app_setup.iss ; Inno Setup 脚本包含 arcGIS Engine Runtime 静默安装调用 #define MyAppName GIS 工具箱 #define MyAppVersion 1.0.0 #define MyAppExeName GISTool.exe #define EngineRuntimeSetup Setup.exe ; arcGIS Engine Runtime 安装介质 #define EngineRuntimeSilentArgs /qb ; 静默安装参数见下方说明 [Setup] AppId{{8A3C2B1E-2D4A-4B6C-9A1D-3F5E6C7A8B9C} AppName{#MyAppName} AppVersion{#MyAppVersion} DefaultDirName{autopf}\{#MyAppName} OutputBaseFilenameGIS_Tool_Setup Compressionlzma2 SolidCompressionyes ; 程序集随包安装关闭“目标机 GAC 优先”的奇奇怪怪加载逻辑 UsePreviousAppDirno [Files] ; 你的整个 bin 目录 Source: ..\bin\*; DestDir: {app}; Flags: recursesubdirs createallsubdirs ; arcGIS Engine Runtime 安装介质放进安装包不额外要求用户单独下载 Source: install\AERuntime\{#EngineRuntimeSetup}; DestDir: {tmp}\AERuntime; Flags: deleteafterinstall [Run] ; 先装 Runtime然后启动你的程序主安装逻辑 Filename: {tmp}\AERuntime\{#EngineRuntimeSetup}; Parameters: {#EngineRuntimeSilentArgs}; \ StatusMsg: 正在安装 arcGIS Engine Runtime请稍候...; Flags: waituntilterminated; \ Check: EngineRuntimeNotInstalled Filename: {app}\{#MyAppExeName}; Description: 启动 GIS 工具箱; \ Flags: postinstall nowait skipifsilent [Icons] Name: {autoprograms}\{#MyAppName}; Filename: {app}\{#MyAppExeName} [Code] function EngineRuntimeNotInstalled(): Boolean; begin // 简单检测判断注册表里是否存在 Engine Runtime 的安装标记 // 10.x 的安装标记通常位于 HKLM\SOFTWARE\ESRI\ArcGIS\Engine 或 // HKLM\SOFTWARE\WOW6432Node\ESRI\ArcGIS\Engine这里只做目标键存在性检测 Result : not RegKeyExists(HKLM, SOFTWARE\ESRI\ArcGIS\Engine10.x); end;这段脚本里的Source用recursesubdirs把整个 bin 递归装进去比一条条列 dll 路径好维护得多。{tmp}目录用来暂存 Runtime 安装介质装完自动删除避免用户 C 盘残留安装文件。3.3 参数怎么调静默参数和等待逻辑EngineRuntimeSilentArgs这里写的是/qb这是常见 Windows Installer 的界面对话参数/qb表示仅显示进度条不显示交互确定页/qn表示完全无界面。arcGIS Runtime 的 Setup.exe 实际上是一个引导程序它支持把参数透传给内层 msi常见的静默组合是/qb但要注意有的版本在接受/qn时会在最后停留在一个“安装完成”界面等待用户点确定这在无人值守安装时会有问题。Flags: waituntilterminated是必须的。如果不加这个标记Inno Setup 不会等 Runtime 装完就直接往下走你的程序先装好了但 ArcObjects 原生库还不存在用户双击时依然是“加载 dll 失败”。这个“顺序依赖”是安装包最容易忽略的点程序文件落盘和运行时安装是异步的必须用这个标志把两步串行起来。3.4 为什么建议把 Runtime 安装介质塞进安装包有人会觉得 arcGIS Engine Runtime 安装包体积大动不动几百 MB把它塞进自己的安装包会让交付文件变得很臃肿。但从部署成功率角度看这样最稳第一目标机器上有没有 Runtime、是什么版本实施人员现场根本不可控你挨个去问客户机器上装没装过 arcGIS沟通成本极高第二从官方渠道单独下载需要登录并选对版本客户现场的 IT 运维不一定有这个耐心。把 Runtime 安装介质内置后安装包变成“双阶段安装”第一阶段装 Runtime第二阶段装你的程序。这比让客户先装 Runtime 再装你的程序要可靠得多。体积大一点可以接受因为面向内部的行业应用交付频率不高体积不是首要矛盾。4. 许可初始化是 arcGIS Engine 部署里最容易失败的环节4.1 单机许可和浮动许可打包时要决定走哪条路arcGIS Engine 应用在目标机器上能不能跑起来最终取决于许可是否初始化成功。打包前必须确定客户现场采用哪种授权方式。常见的两种单机许可Single Use和浮动许可Concurrent Use。单机许可适合在封闭网络环境、无许可服务器的机器上使用。部署时把许可文件放到目标机器指定位置然后通过命令行工具初始化。浮动许可适合几十台机器共用一套授权部署时只需写入许可服务器地址客户端启动时去服务器取席位。在安装包里做许可处理时建议做一个选择页面或配置文件项让实施人员按现场情况填写。写死在脚本里会让维护变成灾难比如客户原来有 50 台浮动许可后来买了几台独立机器要用单机许可你就得重新出包。4.2 许可初始化命令与常见做法在开发机上装完 arcGIS Engine 后系统会带一个许可管理工具名字通常是“ArcGIS Administrator”。界面上可以操作的事部署时都要尽可能变成命令行。因为安装包是无界面安装不可能让现场人员打开 GUI 去点。常见做法是安装完成后调用许可初始化命令。以一个 10.x 版本的示例写入浮动许可服务器地址的方式是在注册表里直接写入服务器名# PowerShell 脚本设置 arcGIS Engine 浮动许可服务器地址 # 以管理员权限运行。32 位程序在 64 位系统上要同时检查两个注册表位置 $regPath HKLM:\SOFTWARE\ESRI\License10.x\ArcGIS Engine $regPathWow64 HKLM:\SOFTWARE\WOW6432Node\ESRI\License10.x\ArcGIS Engine # LICENSE_SERVER 的取值示例27004licserver.contoso.com $licenseServer 27004licserver.contoso.com if (Test-Path $regPath) { New-ItemProperty -Path $regPath -Name LICENSE_SERVER -Value $licenseServer -PropertyType String -Force } if (Test-Path $regPathWow64) { New-ItemProperty -Path $regPathWow64 -Name LICENSE_SERVER -Value $licenseServer -PropertyType String -Force } # 检测写入结果 Get-ItemProperty -Path $regPath | Select-Object LICENSE_SERVER这段命令只在已有上述注册表路径的机器上写入如果没有对应键说明 Runtime 没装成功需要回头排查安装阶段。27004是浮动许可服务默认端口如果客户的许可服务器改过端口这里的值也要跟着变。4.3 初始化许可的 3 个必调参数许可相关配置有三个参数值得在部署时仔细核对参数推荐值说明LICENSE_SERVER27004主机名或主机名浮动许可地址。只写主机名的话用默认端口但显式写端口更不容易踩需要额外解析的坑许可级别初始化等级和你开发时一致例如开发时是 Engine 标准版目标机器也要有同样等级的许可。等级不够时初始化不报错但某些类在创建时抛出“无法创建对象”异常许可缓存文件路径记入安装日志单机许可的缓存文件路径变化会导致程序找不到许可安装时记录在案排错时少走弯路这里最容易踩的坑是许可初始化没报错但实际没生效。开发机上双击运行程序界面正常弹出拿到目标机器上程序也能弹窗但一执行打开地图、读 shp 这类操作就崩。这种“部分功能失效”的现象通常就是许可等级不对或者程序里初始化许可的代码写死了所有功能模块而目标机器的许可只有部分模块。5. 目标机器上装完跑不起来按这四个位置定位问题很多人装完 arcGIS Engine 程序后遇到闪退第一反应是重装 Runtime或者换一台机器试这其实没有命中要害。我用过的最有效的定位办法是按下面四个位置逐个检查。先看事件查看器Windows 日志里“应用程序”一栏找到对应程序的错误记录。如果错误是“CLR20r3”说明是 .NET 程序集版本加载失败如果错误指向某个 esri 原生 dll说明 Runtime 没装或者版本不匹配如果错误是“0xc000007b”大概率是 32/64 位不匹配。这三类原因对应三种完全不同的修法所以先看事件日志比胡乱重装效率高得多。再看程序目录下的 config 文件。arcGIS Engine 程序通常会有 app.config 或 exe.config里面有 bindingRedirect 节点。开发机上跑得好好的机器目标机上报“未能加载文件或程序集 ESRI.ArcGIS.Version”多半是这里的版本重定向缺失或范围太小。不要直接删 bindingRedirect也不要一口气配十几个 dll 的重定向先找到报错的那个版本号把它加进去。第三看许可状态。在目标机器上打开许可管理工具的界面看许可是否显示“可用”。如果显示“不可用”或“无许可”回到第四节的注册表命令检查 LICENSE_SERVER 是否被安装后的其他程序改写过。曾见过一种情况机器上装了 arcGIS Desktop 又装了 Engine 程序Desktop 的许可管理把自己设置成了默认覆盖了 Engine 程序的服务器配置。第四看出厂自带的数据路径。很多 arcGIS Engine 程序启动时要读取固定的工作空间或 mxd 路径开发机上用绝对路径写死了部署到目标机后路径不存在程序在初始化阶段就直接退出。这不是打包问题却是部署失败最常见的原因。在安装包里加一个“数据目录选择”步骤或者程序里改成相对路径都能避免。最后补一个实用技巧发布包含 arcGIS Engine Runtime 的安装包后在目标机上先不运行你自己的程序而是打开 Runtime 自带的一个简单验证工具比如 ArcGIS 安装目录里的一些示例或许可验证程序能不能正常打开能打开就说明 Runtime 和许可没问题问题在你的程序配置上打不开则回头检查 Runtime 安装和许可初始化。这样把“运行时问题”和“程序问题”一刀切开排错路径会清晰很多。本文还有配套的精品资源点击获取