TerraExplorer二次开发C#示例：COM互操作与三维标绘

简介这份 TerraExplorer 二次开发 C# 示例代码面向已有一定 C# 与 GIS 基础、希望借助 Skyline 平台进行三维地球定制开发的开发者重点解决 SDK 调用、地图对象控制、事件响应与数据加载等入门到进阶问题。压缩包共 21 个文件、约 42KB以 C# 源码和 resx 资源文件为主辅以 shp、dbf、shx、prj 等 Shapefile 数据及 fly 飞行文件、解决方案与项目配置便于在 Visual Studio 中直接打开并对照调试。已有 484 人学习下载说明其作为轻量示例集具有一定参考价值。代码围绕地图对象与控件、三维模型加载、空间查询分析、自定义界面及网络服务集成等知识点展开读者可从中了解 TerraExplorer SDK 的基本调用方式、事件驱动流程和工程组织方法并以此为骨架扩展自己的三维 GIS 应用。1. 一次演示临场改需求C# 示例代码要替 TerraExplorer 干的那些活最难受的不是模型难看是演示前半小时需求变了地图上点一下就要自动出标注、镜头推到指定视角、结果还得存回工程文件。手工在客户端里点二十遍改一次需求就重来一遍。搜 skyline 二次开发的人最后基本都落到 TerraExplorer 这套 COM 接口上而 TerraExplorer 二次开发 C# 示例代码正是把接口翻译成业务动作的那一层。这份示例代码要解决的问题很具体用 C# 把打开工程、坐标换算、点线面标绘、飞行定位、鼠标拾取这几件事封装成可复用的类而不是散在窗体代码里的一大堆直接调用。它适合两类人一类是手上已有 .fly 工程想在上面加业务逻辑的开发者另一类是刚接触三维客户端、想先跑通一个最小可运行样例再动手改的新手。读下去你至少能把环境跑起来、能加一个自己的标绘按钮、能看懂事件为什么没进来。2. 项目全貌与技术栈COM 互操作如何把桌面客户端变成可编程引擎TerraExplorer 本身是个装在 Windows 上的三维客户端它对外暴露的是一套 COM 组件你用 C# 写代码本质上是在外面遥控这个客户端。这个定位决定了很多细节进程位数要对、COM 要注册、对象要手动释放、事件要跨线程。示例代码的价值不在于把每个接口都调一遍而在于把这层遥控关系包装成业务代码能接受的样子。我一般会把这类项目拆成三块看宿主窗体程序负责生命周期和 UI、会话封装只管跟 COM 打交道、业务封装标绘、飞行、事件转发不直接出现 Interop 类型。三块边界清不清楚决定了这个示例能不能被拿去二次开发还是只能当个玩具。2.1 目录结构四个工程各管一摊示例代码的目录我按职责拆开比把所有东西塞进一个 WinForms 工程要好改很多。下面是我拆分后的样子TE.Samples/ ├─ TE.Samples.sln ├─ src/ │ ├─ TE.Samples.WinForms/ # 宿主窗体只有 UI 和按钮 │ │ ├─ MainForm.cs │ │ ├─ MainForm.Designer.cs │ │ ├─ TeHostPanel.cs # 承载 ActiveX 控件的面板 │ │ └─ app.config │ ├─ TE.Samples.Core/ # 会话、标绘、事件的封装层 │ │ ├─ TeSession.cs # 启动、打开工程、释放 │ │ ├─ TePlotter.cs # 点线面、文字标签 │ │ ├─ TeNavigator.cs # 飞行、视角 │ │ ├─ TeEventBridge.cs # COM 事件转 EventHandler │ │ └─ CoordHelper.cs # 经纬度/投影换算 │ └─ TE.Samples.Models/ # 纯 POCO不引用任何 Interop │ └─ PlotItem.cs ├─ lib/ │ └─ Interop.TerraExplorerX.dll # 由本机注册表生成的互操作程序集 └─ data/ ├─ sample.fly # 演示用工程 └─ icons/ # 自制点样式图标目录职责能不能脱离 COM 编译TE.Samples.WinForms窗体、按钮、状态栏能但要引用 CoreTE.Samples.Core唯一允许出现SGWorld的地方不能TE.Samples.Models业务数据结构能libInterop 程序集与第三方 dll不涉及data工程文件与素材不涉及关键在于TE.Samples.Models不引用 Interop。很多人图省事把IPosition、ITerraExplorerObject这些接口类型一路往上透传到窗体和业务层结果写单元测试时不得不启动整个三维客户端一个断言跑十秒最后干脆不写测试。把 COM 类型关在 Core 里对外只暴露PlotItem、double[]、int这类普通类型后面想换实现或者做离线回放都不用大改。这也是我看一个示例代码值不值得抄的第一眼Core 里出现using TerraExplorerX;正常Models 里出现就该皱眉了。2.2 技术栈选型.NET Framework、WinForms、x86 与 Interop 版本对齐技术栈这块没什么花活但每个选择都有理由乱换会翻车。运行时用 .NET Framework 4.6.2 及以上不用 .NET 6/8。原因很实际这套接口是 COM 加 ActiveX桌面端宿主最稳的组合仍是 Framework 加 WinForms跨平台运行时对 ActiveX 宿主支持基本没有。你要是想用 WPF 也不是不行但控件承载会多一层 WindowsFormsHost事件时序更绕示例代码没必要给自己加难度。平台目标必须锁 x86。客户端本身长期是 32 位进程宿主位数跟它不一致时连接阶段就会在 COM 类工厂那里报错而且报错信息完全不指向位数问题这是新手最容易卡住的地方。我一般在 csproj 里直接写死不给自己留AnyCPU的幻想!-- TE.Samples.WinForms.csproj 关键节点 -- PropertyGroup TargetFrameworkVersionv4.6.2/TargetFrameworkVersion !-- 必须跟三维客户端位数一致通常就是 x86 -- PlatformTargetx86/PlatformTarget Prefer32Bittrue/Prefer32Bit !-- 引用的 Interop 建议独立复制事件接口强转才稳 -- AutoGenerateBindingRedirectstrue/AutoGenerateBindingRedirects /PropertyGroup ItemGroup !-- EmbedInteropTypes 保持 false避免事件接口被裁掉 -- Reference IncludeInterop.TerraExplorerX HintPath..\..\lib\Interop.TerraExplorerX.dll/HintPath EmbedInteropTypesfalse/EmbedInteropTypes Privatetrue/Private /Reference /ItemGroupEmbedInteropTypes设为false是我踩过坑后的固定动作。设成true时编译器会把用到的 COM 接口内嵌进你的程序集看起来部署更省事但事件接口里那些以_Event结尾的类型经常被裁掉等你写(ISGWorld72Events_Event)sgWorld强转时运行时给你一个InvalidCastException而且错误信息完全不提互操作类型内嵌。保持独立 dll把Interop.TerraExplorerX.dll一起拷到输出目录问题就没了。Interop 程序集怎么来常见做法是用 Visual Studio 的“添加引用 → COM”选中已注册的类型库或者用对应工具从类型库生成。不要手写这份文件也不要从别的机器上随便拷一份版本对不上的。类型库版本跟你装的客户端大版本挂钩SGWorld后面的数字后缀就是版本号示例里出现SGWorld66、SGWorld71还是别的取决于你本机注册了什么。我的习惯是在 Core 里用using别名集中一处改版本只改一行// TE.Samples.Core/TeTypes.cs // 版本后缀以本机 Interop 里实际存在的类型为准全项目只在这里出现一次 using SGWorldAlias TerraExplorerX.SGWorld72; namespace TE.Samples.Core { internal static class TeTypes { // 后续所有代码用 TeTypes.World 而不是直接写 SGWorld72 public static SGWorldAlias CreateWorld() new SGWorldAlias(); } }这样将来客户端升级、Interop 重新生成只要改TeTypes.cs一处业务代码不受牵连。有人说用dynamic更省事别用——事件挂接、out参数、接口强转在dynamic下全是运行时错误编译期什么都发现不了等于给自己埋黑匣子。2.3 三步跑通环境准备、引用设置与启动顺序先说结论这个示例从零到看见画面卡人的环节只有三个。第一步装客户端并确认 COM 注册。装完之后随便写个最小控制台程序new一下SGWorld不抛异常就说明注册表里有了。抛0x80040154就别往下走了先解决注册问题后面写的所有代码都跑不起来。第二步重新生成 Interop。别用别人给的 dll用你自己机器上注册的类型库生成一份版本后缀对齐。生成完在项目里引用EmbedInteropTypes按上一节设成falsePrivate复制到本地设成true。第三步注意启动顺序。会话对象必须先建工程必须先开然后才能创建任何对象或挂事件。顺序错了不会立刻报错但你会得到一个空场景事件也不进来很迷惑。启动代码长这样// TE.Samples.WinForms/MainForm.cs private TeSession _session; private TeEventBridge _bridge; private void MainForm_Load(object sender, EventArgs e) { _session new TeSession(); try { // 1) 建会话连上或拉起客户端 _session.Start(); // 2) 开工程路径建议用绝对路径相对路径受工作目录影响 _session.OpenProject(Path.Combine(AppDomain.CurrentDomain.BaseDirectory, data, sample.fly)); // 3) 挂事件必须在工程打开之后否则拿到的对象是空壳 _bridge new TeEventBridge(_session); _bridge.TerrainPicked OnTerrainPicked; } catch (COMException ex) { // 把 HRESULT 打到状态栏现场排查比 MessageBox 有用 statusLabel.Text $启动失败 HRESULT0x{ex.HResult:X8}; } }Start()先于OpenProject()OpenProject()先于挂事件这三步顺序别调。AppDomain.CurrentDomain.BaseDirectory而不是Environment.CurrentDirectory是因为双击运行和从 IDE 启动的工作目录不一样用后者在现场机器上基本必错。窗体关闭时还有一步清理代码在 3.1 节统一讲这里先记住漏了释放任务管理器里会常驻一个客户端进程重新调试时会连到上次那个僵着的实例上改代码看不到效果非常消耗时间。3. 核心链路拆解从 Project.Open 到一次落点标注这一章是整份示例代码的主体。一条完整的业务链路是建会话 → 开工程 → 造位置对象 → 创建标绘 → 控制视角 → 关工程释放。下面按顺序拆每段代码都可以直接抄进你的项目改。3.1 会话生命周期Start、Open 与 Dispose会话封装的核心就三件事只建一次、开工程、释放干净。写成类而不是散在窗体的字段里是为了让释放时机可控。// TE.Samples.Core/TeSession.cs public sealed class TeSession : IDisposable { private SGWorldAlias _world; // 别名指向本机 Interop 版本 private bool _ownsProject; // 对外只暴露接口业务层不需要知道 COM 细节 public SGWorldAlias World _world ?? throw new InvalidOperationException(会话未启动); public void Start() { // 单例重复 new 可能连到不同实例事件和对象都对不上 if (_world ! null) return; _world TeTypes.CreateWorld(); } public void OpenProject(string flyPath, string password ) { if (!File.Exists(flyPath)) throw new FileNotFoundException(工程文件不存在, flyPath); // 第二个参数是工程密码没有就传空串传 null 在某些版本会报参数错误 _world.Project.Open(flyPath, password ?? string.Empty); _ownsProject true; } public void Dispose() { try { // 只关工程不关客户端进程要不要退进程由宿主决定 if (_ownsProject _world ! null) _world.Project.Close(); } catch (COMException) { // 客户端已被用户手动关掉时会抛忽略即可 } finally { if (_world ! null) { // 引用计数归零否则进程常驻 Marshal.FinalReleaseComObject(_world); _world null; _ownsProject false; } } } }逻辑说明几处。Start()里的if (_world ! null) return;看着像废话其实是防重复创建每个new出来的会话对象背后都可能对应一次组件实例化你 if 里 new 两个事件挂在前一个、标绘画在后一个表现就是“点了没反应”。Project.Open的两个参数第一个是.fly工程路径建议传绝对路径第二个是工程密码没有密码传空串别传null不同版本对null的处理不一致有的直接抛参数异常。Project.Close()关的是工程文档不是客户端进程。宿主要退出时先Close再FinalReleaseComObject两步都做。只Close不释放进程残留只释放不Close客户端可能弹一个“是否保存”的对话框卡在那里。3.2 位置对象CreatePosition 的四个易错参数三维场景里所有东西都要落到一个位置上位置对象造错了后面标绘、飞行全跟着错而且错得很有迷惑性——标注跑到海里、飞到地下、图标埋进山体。造位置的代码如下// TE.Samples.Core/TePlotter.cs片段 private static IPosition BuildPosition(SGWorldAlias world, double lon, double lat, double alt) { return world.Creator.CreatePosition( lon, // 经度单位度东正西负 lat, // 纬度单位度北正南负 alt, // 高度数值含义由下一个参数决定 AltitudeTypeCode.ATC_TERRAIN_RELATIVE, // 高度基准相对地形 0, // Yaw偏航角度 0, // Pitch俯仰角度 0, // Roll翻滚角度 0); // Distance观察距离米 }四个容易出错的参数我一个一个说。第一是经纬度顺序。这个接口是先经度后纬度跟我们平时说“北纬东经”的习惯相反。写反了不会报错标注会跑到地球另一边你会以为是坐标系问题查半天。第二是单位。传度不是度分秒也不是弧度。从 GPS 或测绘成果里拿到的往往是度分秒字符串先转成十进制度再传转换代码在CoordHelper里别在调用处现算。第三是AltitudeTypeCode。ATC_TERRAIN_RELATIVE表示高度是相对地形的高度传 0 就贴地绝对高度用另一个枚举值此时高度是海拔还有直接贴地不管高度的选项。三个选错了表现分别是“飞得特别高”“钻到地下”“贴地正常但缩放后悬空”。我一般默认用相对地形因为业务上说的“离地 50 米”最直观。第四组是姿态三件套和Distance。做文字标签时全是 0 没问题做模型摆放时Yaw决定朝向随手传 0 会导致所有车辆模型都朝正北一堆车排成一条线。Distance是镜头与目标的观察距离做“飞过去看一眼”的时候有用传 0 表示用默认距离。投影坐标别直接往里塞。有些业务数据是平面米制坐标直接传给这个接口位置会偏得离谱。正确做法是先做投影反算变成经纬度或者用坐标转换服务转一道这块在 5.4 节的坑里再展开。3.3 标绘三件套文字标签、折线、多边形与图层分组标绘这块示例代码里最值得抄的是分组管理。不做分组几十个对象全堆在工程树的根上客户第一句反馈就是“太乱”。先看分组// TE.Samples.Core/TePlotter.cs片段 private readonly SGWorldAlias _world; private readonly Dictionarystring, int _groupCache new Dictionarystring, int(); public int EnsureGroup(string name, int parentGroupId 0) { if (_groupCache.TryGetValue(name, out var cached) cached ! 0) return cached; // 先找同名分组避免重复打开工程时越建越多 var group _world.ProjectTree.GetGroup(name); if (group null) group _world.ProjectTree.CreateGroup(name, parentGroupId); _groupCache[name] group.ID; return group.ID; }_groupCache这层缓存不是性能优化是防重复。工程里已经有同名分组时CreateGroup会按名字建一个新的或者直接失败取决于版本。先GetGroup再建幂等重复执行不会污染工程树。然后是文字标签public int PlotLabel(double lon, double lat, double alt, string text, string groupName 业务标注) { var pos BuildPosition(_world, lon, lat, alt); int groupId EnsureGroup(groupName); // CreateColor 参数顺序是 透明度、红、绿、蓝别当 RGB 用 uint fore _world.CreateColor(255, 255, 208, 0); uint back _world.CreateColor(140, 0, 0, 0); var label _world.Creator.CreateTextLabel( pos, text, fore, back, 12, // 字号像素 Microsoft YaHei, // 字体现场机器没这字体就退默认 false, // 粗体 false, // 斜体 groupId); return label.ID; // 句柄一定留着改文字、删对象都靠它 }颜色这个坑值得单独说。CreateColor的四个参数是透明度在前、RGB 在后跟常见的Color.FromArgb顺序一致但跟很多图形库的 RGB 顺序不同。我第一次写的时候按 RGB 传透明度和红色正好对调结果标注全成了半透明红块。返回的ID必须存。后续改文字、改位置、删对象全靠这个整数句柄。示例里我用Dictionaryint, PlotItem维护一份句柄到业务对象的映射删的时候先查再删不做就会删错。折线和多边形用几何对象创建public int PlotPolyline(IListdouble[] wgs84Points, string groupName 轨迹) { if (wgs84Points null || wgs84Points.Count 2) throw new ArgumentException(折线至少需要两个点); // 摊平成 [lon,lat,alt, lon,lat,alt, ...] var flat new Listdouble(wgs84Points.Count * 3); foreach (var p in wgs84Points) { flat.Add(p[0]); flat.Add(p[1]); flat.Add(p[2]); } var geo _world.Creator.GeometryCreator .CreateGeometryFromArray(flat.ToArray()); uint color _world.CreateColor(255, 0, 200, 255); // 线宽单位像素第三个参数传 0 会用默认宽度 var line _world.Creator.CreatePolyline(geo, color, 3, EnsureGroup(groupName)); return line.ID; }摊平数组这里CreateGeometryFromArray期望的是连续的三元组高度不能省。有人只传经纬度两元组几何会创建失败或者高度全按 0 处理线直接贴在地表——看着能用一旦有高差就穿模。多边形接口跟折线基本一样把方法换成创建面的那个、并且要求首尾闭合或者让接口自动闭合取决于版本其余逻辑照抄。裁剪的时候记住分组是逻辑删除的抓手。要清空某类标注遍历工程树里对应分组下的子对象删掉比维护一堆句柄更省心。3.4 视角控制FlyTo、JumpTo 与镜头姿态视角控制就两个动作飞过去、瞬间切过去。区别在于有没有动画过程。// TE.Samples.Core/TeNavigator.cs片段 public void Focus(double lon, double lat, double alt, bool animated true) { var pos BuildPosition(_world, lon, lat, alt); // 动画飞行会打断用户当前操作做“一键复位”按钮用 Jump 更合适 _world.Navigate.FlyTo(pos, animated ? ActionCode.AC_FLY_TO : ActionCode.AC_JUMP_TO); } public void ResetView(double lon, double lat, double alt) { // 复位用瞬移避免用户连点两次按钮时动画排队 Focus(lon, lat, alt, animated: false); }这里有个隐藏行为要注意AC_FLY_TO是异步动画。调用返回不代表镜头到位了紧接着读取当前相机位置或者做截图拿到的还是旧视角。要等动画结束常规做法是挂帧事件在第 N 帧后判断距离或者简单点用定时器延时。做导出视频这类需求时不等动画结束就截图导出的一定是开头几帧的糊图这个坑很典型。姿态参数在位置对象里就已经带了旋转场景可以复用同一个BuildPosition只把Yaw、Pitch、Roll改成需要的角度。Pitch是俯仰做“斜向下 45 度俯瞰”就是这个参数很多人误以为要去改相机高度结果调半天比例不对。4. 交互层鼠标事件、动态对象与宿主窗体前面几节是单向输出——代码告诉场景画什么。交互层是反过来的用户在场景里点了代码要知道。这一层是最容易出玄学问题的地方因为事件来自 COM 线程而你手上的控件属于 UI 线程。4.1 事件桥接把 COM 回调安全地送回 UI 线程事件挂接需要把会话对象强转成对应版本的事件接口然后挂委托。把它单独封一层好处是你以后再也不用在业务代码里写强转。// TE.Samples.Core/TeEventBridge.cs public sealed class TePickEventArgs : EventArgs { public double Lon { get; } public double Lat { get; } public double Alt { get; } public TePickEventArgs(double lon, double lat, double alt) { Lon lon; Lat lat; Alt alt; } } public sealed class TeEventBridge : IDisposable { private readonly SGWorldAlias _world; private readonly ISGWorldEvents_Event _source; // 事件接口版本跟会话保持一致 public event EventHandlerTePickEventArgs TerrainPicked; public TeEventBridge(TeSession session) { _world session.World; // 强转必须成功失败多半是 EmbedInteropTypes 或版本不一致 _source (ISGWorldEvents_Event)_world; _source.OnLButtonClicked OnLButtonClicked; } private void OnLButtonClicked(int flags, int x, int y) { object lonObj, latObj, altObj; // 屏幕像素打到地形上拿回经纬度和高程打到天空会返回 false bool hit _world.Window.PixelToWorld( x, y, PixelToWorldTypeCode.PWCT_TERRAIN, out lonObj, out latObj, out altObj); if (!hit) return; TerrainPicked?.Invoke(this, new TePickEventArgs(Convert.ToDouble(lonObj), Convert.ToDouble(latObj), Convert.ToDouble(altObj))); } public void Dispose() { // 先摘委托再释放会话顺序反了会留下野引用 _source.OnLButtonClicked - OnLButtonClicked; } }PixelToWorld三个out是object得自己转double。返回值是布尔点在地形外比如天空背景会返回false此时三个out是无效值不判布尔直接转会得到一堆莫名其妙的坐标。真正的坑在跨线程。OnLButtonClicked由客户端的 COM 线程回调不是 UI 线程。你在里面直接改label.Text轻则界面不刷新重则抛跨线程访问异常而且这种异常在调试器里有时被吞掉表现就是“偶尔崩、偶尔正常”。正确的姿势是宿主侧统一Invoke// TE.Samples.WinForms/MainForm.cs private void OnTerrainPicked(object sender, TePickEventArgs e) { if (InvokeRequired) { // COM 线程回调转到 UI 线程再碰控件 BeginInvoke(new Action(() OnTerrainPicked(sender, e))); return; } statusLabel.Text $拾取 {e.Lon:F6}, {e.Lat:F6}, 高 {e.Alt:F1} 米; txtLon.Text e.Lon.ToString(F6); txtLat.Text e.Lat.ToString(F6); }InvokeRequired判断加BeginInvoke是标准写法。用BeginInvoke而不是Invoke是因为事件可能在短时间内连续触发同步等待会阻塞 COM 线程手感变卡。4.2 动态对象实时目标的创建、更新与销毁静态标绘适合“结果”动态对象适合“过程”比如目标跟踪、车辆沿轨迹移动。动态对象的特点是位置可以高频更新而且开销比反复删了重建小得多。// TE.Samples.Core/TePlotter.cs片段 public IDynamicObject CreateTrack(int templateId, string groupName 动态目标) { // 拿一个已有的静态对象当模板样式直接继承省得逐个设参数 var template _world.ProjectTree.GetObject(templateId); if (template null) throw new ArgumentException(模板对象不存在); return _world.Creator.CreateDynamicObject( template, // 模板对象 DynamicObjectTypeCode.DOT_POINT, // 动态类型点/线/面 EnsureGroup(groupName)); } public void UpdateTrack(IDynamicObject track, double lon, double lat, double alt) { // 每帧调用不要再重新 Create复用同一个动态对象 track.SetPosition(BuildPosition(_world, lon, lat, alt)); } public void RemoveTrack(IDynamicObject track, int objectId) { if (track ! null) track null; // 先丢引用 _world.Creator.DeleteObject(objectId); // 再按句柄删研究对象 }创建时用模板是为了继承样式。你不给模板、现场手搓一个图标配置很容易出现“动态点和静态点长得不一样”的尴尬。模板对象建议放在一个专门的隐藏分组里创建完动态对象后模板保持隐藏用户看不见。更新频率别太高。定时器设 50 毫秒20 帧看着流畅但目标一多画面就开始卡。我一般按业务需要取 100 到 200 毫秒配合简单的插值视觉上够用且稳。真要做到 60 帧那是另一套渲染思路别在客户端标绘层死磕。销毁这块有个血泪经验CreateDynamicObject创建的对象和模板对象是两个不同 ID但如果你把模板 ID 记混了删的时候会把模板删掉后续所有动态对象都创建失败。所以句柄一定分开存命名上就区分templateId和dynamicId别都用id。4.3 弹窗与窗口HTML 气泡、消息条和 ActiveX 嵌入交互反馈有三种按信息量从轻到重排状态栏文字、气泡弹窗、嵌入页面。状态栏最简单直接往宿主窗体写不用碰客户端。气泡弹窗适合“点了标注看详情”内容是 HTML能放表格和图片// 在拾取到对象后弹一个详情气泡 public void ShowDetail(int screenX, int screenY, string title, string htmlBody) { // 位置是屏幕像素直接透传鼠标事件里的 x/y 即可 // 参数含义依次为标题、HTML 内容、X、Y、宽、高 _world.Creator.CreatePopupMessage(title, htmlBody, screenX, screenY, 320, 200); }HTML 内容里有两点注意。一是图片和样式表用绝对路径或者内联 base64相对路径在弹窗里解析不到白框一片。二是脚本能力有限别在里面写复杂交互弹窗就是展示层要交互就回宿主窗体做。如果要嵌整个客户端到自己窗体里用的是 ActiveX 控件。做法是把控件拖到 WinForms 面板上控件会暴露会话对象通过它拿到跟 3.x 节一样的入口。这条路的好处是界面统一、不用切进程坏处是控件版本跟客户端绑定部署时容易缺依赖而且控件承载在 WPF 里要额外套一层。我的取舍是交付给最终用户的产品用嵌入内部工具和快速验证用独立进程加 COM 连接后者调试省事得多。5. 避坑与排查五个我真实翻过的车这一章全是排错。这类项目的报错信息普遍不友好HRESULT 一个数字丢给你什么都不说。下面五条按现象、原因、解决写遇到问题时按顺序对号入座。5.1 检索 COM 类工厂失败0x80040154现象编译没问题一运行就抛COMExceptionHResult是0x80040154提示“没有注册类”。原因三种可能——机器上根本没装客户端装的是绿色版或免安装版没往注册表写类型库宿主位数跟客户端位数不一致32 位宿主在 64 位注册表里找不到 32 位组件。解决先确认装的是正常安装版重装一遍最省时间再用注册表搜索确认类型库存在最后检查项目平台目标锁死 x86。三条都对还报错就把生成目录下的 Interop dll 删掉重新引用有时是旧的 dll 覆盖了新的。5.2 AnyCPU 编译通过运行就抛 COMException现象开发机上一切正常拷到另一台机器直接崩或者开发机换成 64 位调试就崩。原因AnyCPU在 64 位系统上默认以 64 位进程跑COM 组件是 32 位的跨位数调用直接失败。开发机能跑往往是因为 IDE 里勾了“首选 32 位”。解决PlatformTarget显式写x86别依赖Prefer32Bit一个开关。同时把生成配置里的平台下拉框也改成 x86两处都要改只改一处会出现在 IDE 里跑得通、命令行构建出来的跑不通。5.3 事件死活不触发现象鼠标点在场景里没反应断点打不进回调但标绘、飞行都正常。原因大概率三个之一——事件挂在了另一个会话实例上重复newInterop 的内嵌类型把事件接口裁掉了强转其实没成功但被as静默吞了事件在工程打开之前挂的对象还没就绪。解决会话改成单例全局只留一个实例EmbedInteropTypes设false用强制转换而不是as让失败第一时间抛出来挂事件放到工程打开之后。排查时在强转那行打断点能过就说明是时序问题过不去就是类型问题。5.4 标注点凭空偏移现象标绘的点不在预期位置偏几百米到几公里不等方向也不固定。原因把平面投影坐标当成经纬度传进去了或者经纬度顺序写反或者高度基准选错导致视觉上“飘”。解决先打印传进去的数值经度应该在 -180 到 180、纬度在 -90 到 90 区间出现几千几万这种数就说明是投影坐标先做反算。顺序问题靠打印分辨经度绝对值比纬度大很多的地方反了会很显眼。高度问题就看缩放时标注是不是跟着地形起伏不跟着就是基准选错。5.5 换台机器就找不到工程和图标现象开发机上好好的部署到现场机器工程打不开或者标注的图标全是空白方块。原因路径写的是开发机的绝对路径工程文件内部引用素材用的是相对路径而你的工作目录不对图标文件没跟着发布。解决宿主侧统一用程序集所在目录拼路径不用当前工作目录工程内的素材引用尽量用相对路径并且保证.fly与素材目录的相对结构在发布包里一致发布时把data目录整体带上别只拷.fly一个文件。图标这种小文件最容易漏我一般在构建后加一步检查本文还有配套的精品资源点击获取