简介这份资源是面向 .NET 开发者的 GMap.NET 地图开发示例包适合希望在 C# 项目中集成地图功能的初中级开发者以及需要快速上手 Windows Forms、WPF 等平台地图控件的技术人员。压缩包共 40 个文件约 5.45MB以 cs 源码、dll 类库、exe 可执行程序、xaml 界面文件及 pdb 调试文件为主另含 sln 解决方案与 csproj 工程文件可直接在 Visual Studio 中打开运行。示例覆盖地图服务集成、坐标系统、路线规划、点标记与覆盖物、热力图与多边形、图层管理、事件处理、异步加载及自定义地图服务等核心知识点并借助 GMFlow 演示项目展示实际应用方式。目前已有 567 人学习下载读者可通过研读源码掌握地图展示、导航与可视化分析的实现思路并在此基础上扩展个性化地图功能。1. GMAP.NET 离线地图 Demo一个能直接跑起来的 C# 桌面地图壳子如果你接过那种“内网环境、不能连外网、但要在 WinForm 里显示地图和轨迹”的需求大概率绕不开 GMAP.NET。这个GMAP.NETDemo.rar就是一份把 GMAP.NET 跑通的最小可运行工程里面包含地图控件加载、图层切换、标记点绘制、轨迹线绘制这几块最常用的能力语言是 C#宿主是 WinForm。它解决的不是“地图引擎怎么造”而是“在离线或弱网环境下怎么让一个桌面程序把瓦片地图、标记和路径画出来”。适合两类人一类是刚接手 GIS 上位机、监控大屏、车辆调度界面的 C# 开发者想找个能编译、能改、能对照的起点另一类是已经用过在线地图 SDK但被授权、配额、内网部署卡住想换成纯本地瓦片方案的人。这份 Demo 的价值在于它把 GMAP.NET 的初始化、缓存目录、地图提供者、覆盖物这几件事串成了一条能跑通的链路而不是丢给你一个空控件让你自己猜。2. GMAP.NET 的瓦片机制与工程结构先搞懂它怎么把地图“拼”出来2.1 瓦片金字塔与 GMapProvider 的选型逻辑GMAP.NET 的本质是一个瓦片地图渲染器它不生产地图数据只负责按经纬度和缩放级别算出需要哪些瓦片然后去取、去缓存、去拼接。瓦片按 Z/X/Y 三级索引组织Z 是缩放级别X 是列号Y 是行号每个瓦片通常是 256×256 像素的图片。你在地图上平移一次控件内部就在算当前视口覆盖了哪些瓦片编号缺哪块补哪块。选型的核心在GMapProvider。Demo 里常见的是GMapProviders.OpenStreetMap这类公开源但真正落地到内网通常要换成自定义的本地瓦片提供者或者用GMapProviders.EmptyProvider配合自己实现的GetTileImage。这里有个反直觉的点很多人以为换个 Provider 就是换个网址实际上 Provider 决定了瓦片编号规则、投影方式、版权信息甚至坐标系。如果你拿到的离线瓦片是按 TMS 规范切的而 Provider 按 XYZ 规范去取Y 轴是反的地图会上下颠倒——这个坑后面会细说。判断该用哪种 Provider我一般看三条瓦片来源是公开服务还是本地目录、投影是 Web Mercator 还是别的、需不需要带鉴权参数。三条里有一条不匹配就得自己继承GMapProvider重写。2.2 工程目录与关键文件职责解压后先别急着 F5花两分钟认清结构能省很多事。典型结构如下文件/目录职责改动频率Program.cs入口启动主窗体几乎不动MainForm.cs主窗体逻辑控件初始化与事件高频改MainForm.Designer.cs设计器生成的控件布局少手改GMapControl引用地图核心控件不动bin/Debug/编译输出与运行时缓存自动生成packages.config或引用项GMAP.NET 程序集依赖装库时动需要重点确认的是 GMAP.NET 程序集的引用方式。老工程多用packages.config加 NuGet 还原新一点的用PackageReference。如果打开就报找不到GMap.NET.Core或GMap.NET.WindowsForms八成是还原没走通而不是代码问题。2.3 初始化地图控件的可复现步骤下面这段是让地图真正显示出来的最小初始化逻辑我把它拆成可抄的形式// 1. 设置缓存目录离线场景必须显式指定否则默认写到用户目录 GMaps.Instance.Mode AccessMode.ServerAndCache; GMaps.Instance.PrimaryCache new MySqlCache(); // 也可用 SQLite 或纯文件缓存 // 2. 指定地图提供者内网换成自定义 Provider gmap.MapProvider GMapProviders.OpenStreetMap; gmap.Position new PointLatLng(39.9042, 116.4074); // 初始中心点 gmap.MinZoom 3; gmap.MaxZoom 18; gmap.Zoom 12; // 3. 关闭或开启鼠标交互按业务需要 gmap.DragButton MouseButtons.Left; gmap.CanDragMap true; gmap.ShowCenter false;逻辑说明AccessMode决定取瓦片时是只读缓存、只连服务还是两者结合离线部署一般用CacheOnly或ServerAndCache。PrimaryCache是缓存后端Demo 里如果没显式设置会落到默认位置迁移机器时容易丢。Position和Zoom决定初始视野MinZoom/MaxZoom限制用户能缩放的范围避免请求到没有瓦片的层级。参数怎么改中心点经纬度按项目所在地填Zoom初始值建议比MaxZoom小几级留出放大空间DragButton如果设成右键要同步处理右键菜单冲突。2.4 标记点与轨迹线的绘制方式地图能显示只是第一步业务真正要的是“点”和“线”。GMAP.NET 用GMapOverlay承载覆盖物一个 Overlay 是一层可以叠加多层// 创建标记层 GMapOverlay markers new GMapOverlay(markers); GMapMarker marker new GMapMarker(new PointLatLng(39.9042, 116.4074)); marker.Shape new GMap.NET.WindowsForms.Markers.GMarkerGoogle( marker.Position, GMap.NET.WindowsForms.Markers.GMarkerGoogleType.blue_pushpin); markers.Markers.Add(marker); gmap.Overlays.Add(markers); // 创建轨迹层 GMapOverlay routes new GMapOverlay(routes); GMapRoute route new GMapRoute(path1); route.Points.Add(new PointLatLng(39.90, 116.40)); route.Points.Add(new PointLatLng(39.91, 116.42)); route.Stroke new Pen(Color.Red, 3); routes.Routes.Add(route); gmap.Overlays.Add(routes);逻辑说明Overlay 的Id要唯一重复添加同名层会出问题。GMapMarker的Shape决定图标样式内置了几种 pin也可以自定义图片。GMapRoute的Points是经纬度列表Stroke控制线宽和颜色。轨迹点多了以后频繁Add会触发重绘性能敏感场景要批量构造后再一次性加入。参数怎么改图标换成自己的 PNG 时注意尺寸和锚点锚点不对会出现“图标飘在坐标旁边”的现象线宽在缩放时不会自动变需要按 Zoom 动态调整。3. 从零跑通 Demo编译、缓存与离线瓦片接入3.1 环境准备与依赖还原先把环境对齐能省掉一半“玄学”报错。Demo 是 C# WinForm目标框架常见是 .NET Framework 4.x。你需要 Visual Studio2017 及以上都行并勾选“.NET 桌面开发”工作负载。打开解决方案后第一件事是还原 NuGet 包# 在解决方案根目录执行或直接用 VS 的“还原 NuGet 包” nuget restore GMAP.NETDemo.sln如果提示找不到nuget命令用 VS 右键解决方案选“还原 NuGet 包”即可。还原完成后检查引用里GMap.NET.Core和GMap.NET.WindowsForms是否都指向了packages目录下的 dll。常见翻车是只还原了一半WindowsForms没进来编译时报“找不到 GMapControl 类型”。3.2 首次运行与缓存目录确认第一次 F5 运行地图区域可能先白后花这是正常的——它在按当前视口拉瓦片。等几秒如果还是空白先看缓存目录有没有生成文件。默认缓存位置通常在%USERPROFILE%\AppData\Local\GMap.NET\进去看有没有按 Z/X/Y 分层的目录和.png文件。有文件说明取瓦片成功只是渲染或网络慢没文件说明 Provider 没取到数据要查网络或 Provider 配置。离线场景下这一步是分水岭能生成缓存说明链路通不能就得换本地瓦片方案。3.3 接入本地离线瓦片的做法内网部署时公开 Provider 取不到数据常见做法是把预先切好的瓦片放到本地目录然后自定义 Provider 去读。核心是重写GetTileImagepublic class LocalTileProvider : GMapProvider { private readonly string _root; public LocalTileProvider(string root) { _root root; } public override PureImage GetTileImage(GPoint pos, int zoom) { // 按 Z/X/Y 拼路径注意目录层级要和切片工具一致 string path Path.Combine(_root, zoom.ToString(), pos.X.ToString(), pos.Y.ToString() .png); if (!File.Exists(path)) return null; return GetTileImageFromFile(path); } public override GMap.NET.GPoint ProjectFromPixel( GPoint pixel, int zoom) { /* 按投影实现 */ } // 其余抽象成员按 Web Mercator 补齐 }逻辑说明GetTileImage收到的是瓦片编号pos和层级zoom你按自己的目录规范拼出文件路径返回图片即可。返回null表示这块没有控件会留白而不是崩溃。参数怎么改_root指向瓦片根目录如果切片工具输出的是z/x/y还是z/y/x路径拼接顺序必须一致否则整片错位。提示自定义 Provider 时Projection和ProjectFromPixel等抽象成员必须实现完整只实现GetTileImage编译不过。3.4 验证地图是否真的走本地接完本地瓦片怎么确认没偷偷走网络把网线拔了再跑一次地图还能正常显示和缩放就说明走的是本地。另一个办法是看缓存目录是否还在增长——如果本地 Provider 生效它不会再往默认缓存写新文件。这一步别省我见过有人以为切了本地结果 Provider 没换内网一部署就白屏。4. 避坑与排查GMAP.NET 落地时最容易翻车的五件事4.1 地图上下颠倒或左右错位现象地图能显示但整体上下翻转或者相邻瓦片接不上。原因瓦片编号规范不一致TMS 的 Y 轴从下往上XYZ 从上往下两者 Y 值互为镜像。解决在自定义 Provider 里对 Y 做转换Y (1 zoom) - 1 - pos.Y或者换用匹配规范的切片工具重新切。4.2 编译报找不到 GMap.NET 类型现象GMapControl、GMapOverlay全部标红。原因NuGet 没还原完整或引用的 dll 版本和代码不匹配。解决删掉bin和obj重新还原确认GMap.NET.Core与GMap.NET.WindowsForms版本号一致别一个 1.7 一个 1.9。4.3 标记点位置偏移现象标记图标不在指定经纬度上偏了几十像素。原因自定义图标的锚点没设对默认锚点是左上角。解决设置marker.Offset或LocalPosition让图标中心对准坐标点用内置 pin 时一般不用管。4.4 轨迹点多了以后界面卡死现象加载几千个轨迹点后拖动地图明显卡顿甚至无响应。原因每个点单独Add触发多次重绘且 Overlay 没做简化。解决批量构造Points后一次性赋给GMapRoute对轨迹做抽稀或按缩放级别决定显示密度。4.5 离线环境下首次加载空白现象内网机器上地图区域一直白缓存目录也不生成文件。原因Provider 仍指向在线源取不到数据又不报错。解决确认MapProvider已换成自定义本地 Provider检查瓦片目录权限服务账户是否有读权限。5. 进阶把 GMAP.NET 用稳的几个习惯Demo 跑通只是起点真正上线还要处理坐标系、性能和缓存三件事。坐标系上GMAP.NET 默认 Web Mercator如果你拿到的业务数据是 WGS84 或 GCJ02直接丢进去会有几百米偏移常见做法是在入库前统一转成 Web Mercator 再喂给控件。性能上Overlay 数量别超过三层标记超过几百个就考虑用聚合或按视野裁剪否则每次重绘都在遍历全量对象。缓存上离线部署建议把瓦片目录和缓存目录分开瓦片只读、缓存可写避免程序把只读目录当缓存写导致异常。验证是否用稳了我一般做两个动作一是断网跑一遍完整业务流程看有没有隐藏的在线请求二是把地图缩放到MinZoom和MaxZoom两端看有没有越界或空白。这两个动作能挡掉大部分“开发机好好的、现场就崩”的问题。从那以后我每次接地图类需求都强制先确认三件事瓦片规范是 TMS 还是 XYZ、坐标系是什么、离线目录权限够不够。这三条对齐了后面基本不会出大问题。希望帮到你。本文还有配套的精品资源点击获取