简介这份资源是面向.NET开发者的GMap.NET地图开发示例包适合希望在C#项目中集成地图功能的Windows Forms、WPF及ASP.NET开发者尤其适合刚接触GMap.NET、需要快速上手的中初级人员。包内共40个文件以13个cs源码、4个dll类库、2个xaml界面文件、1个sln解决方案及若干exe、pdb、resources等为主压缩包约5.45MB结构完整可直接编译运行。目前已有566人学习下载。示例围绕地图服务集成、地图控件、坐标系统、路线规划、点标记与覆盖物、热力图与多边形、图层管理、事件处理、异步加载及自定义地图服务等核心知识点展开通过GMFlow中的示例代码演示地图展示、导航、标记与覆盖物等实用功能。读者可借助该Demo理解GMap.NET的控件属性设置、多地图源切换与交互事件监听方式并在此基础上扩展个性化地图应用是学习与应用该开源地图库的实用参考。1. 拆开 GMAP.NETDemo.rar一个 C# 桌面地图控件到底能跑出什么如果你手上有一个叫GMAP.NETDemo.rar的压缩包里面躺着GMAP.NET、GMFlow、GMap.net Demo这些关键词那你大概率正在做一件很具体的事在 WinForms 或 WPF 桌面程序里嵌一张能拖动、能缩放、能打点的地图而不是打开浏览器调 JavaScript API。GMap.NET 就是干这个的——一个纯 C# 的桌面地图控件库把瓦片地图的下载、缓存、渲染、投影换算全封装成控件你拖到窗体上就能用。它解决的核心痛点是工业上位机、内网监控、离线部署场景下浏览器方案要么被网络限制卡死要么和现有 C# 代码割裂。适合谁做上位机、做设备管理软件、做内网 GIS 展示的 C# 开发者。这篇不聊虚的从环境搭起来到瓦片缓存踩坑把GMAP.NETDemo这类示例真正跑通、改懂、用稳。2. 环境搭建与第一个可运行窗口从零复现 GMap.net Demo2.1 为什么选 GMap.NET 而不是 WebView 套壳先把这个选型问题说清楚否则后面每一步你都会怀疑自己。桌面端要显示地图常见三条路WebView 嵌网页地图、调用在线地图静态图 API、用 GMap.NET 这类原生控件。WebView 套壳的问题是交互延迟明显鼠标拖动有拖影而且一旦目标机器没有现代浏览器内核或者内网禁了外网整个地图区域直接白屏。静态图 API 更简单但没法连续缩放拖动交互体验差一个档次。GMap.NET 的价值在于它是纯托管代码编译进你的 exe运行时只依赖它自己去请求瓦片图片。瓦片请求走的是标准 HTTP你可以换成内网瓦片服务也可以让它读本地缓存目录。对于内网设备管理、车辆监控、传感器布点这类场景地图底图往往只需要固定几个层级缓存一次就能长期离线用。这就是GMFlow这类流程能成立的前提——地图数据流是可控的、可缓存的、可离线的。另一个现实理由是代码同构。你的业务逻辑、串口通信、数据库访问全是 C#地图控件也是 C# 对象打点就是往Overlay里加GMarkerGoogle不用在 C# 和 JavaScript 之间来回序列化坐标。坐标转换、图层管理、点击事件全在一个进程里调试的时候断点能直接打在地图回调上这个体验是套壳方案给不了的。2.2 用 NuGet 装包并跑起最小窗体不要去找那个 rar 里的 dll 手动引用版本混乱是新手第一个翻车点。直接用 NuGet 装命令和包名如下。注意 GMap.NET 在 NuGet 上分核心库和 WinForms 渲染器两个包少装一个就是编译过、运行报渲染器找不到。# 在 Visual Studio 的包管理器控制台执行 Install-Package GMap.NET.Core Install-Package GMap.NET.WinForms如果你用 .NET CLI等价命令是dotnet add package GMap.NET.Core dotnet add package GMap.NET.WinForms装完之后新建一个 WinForms 项目在窗体代码里手动创建控件。很多人以为拖个控件就行但 GMap.NET 的 WinForms 控件在工具箱里不一定自动出现手动写更稳。using GMap.NET; using GMap.NET.MapProviders; using GMap.NET.WindowsForms; using GMap.NET.WindowsForms.Markers; public partial class MainForm : Form { private GMapControl gmap; public MainForm() { InitializeComponent(); InitMap(); } private void InitMap() { gmap new GMapControl(); gmap.Dock DockStyle.Fill; // 关键先设置管理器模式再设位置否则缓存不生效 GMapProvider.UserAgent YourAppName/1.0; GMaps.Instance.Mode AccessMode.ServerAndCache; gmap.MapProvider GMapProviders.OpenStreetMap; gmap.Position new PointLatLng(39.9042, 116.4074); // 北京 gmap.MinZoom 3; gmap.MaxZoom 18; gmap.Zoom 12; gmap.ShowCenter false; gmap.DragButton MouseButtons.Left; this.Controls.Add(gmap); } }这段代码的逻辑顺序有讲究。GMaps.Instance.Mode必须在控件第一次请求瓦片之前设置设成ServerAndCache表示优先读本地缓存、没有再走网络。UserAgent一定要改用默认值请求瓦片服务容易被限流甚至拒绝这是血泪经验。Position是地图中心点Zoom是初始层级MinZoom和MaxZoom限制用户能缩放到什么程度设太宽会导致请求大量无用瓦片。参数说明AccessMode有三个值ServerOnly只走网络、CacheOnly只读缓存、ServerAndCache两者结合。离线部署时先联网跑一遍把瓦片缓存下来再切CacheOnly。DragButton设成左键拖动符合桌面习惯默认是右键拖动很多人第一次用觉得地图拖不动就是这个原因。2.3 加一个标记和一条折线验证交互链路地图能显示只是第一步真正要验证的是打点和画线。下面这段代码在当前位置加一个标记再画一条折线确认 Overlay 机制正常工作。private void AddMarkerAndRoute() { // 标记层 GMapOverlay markersOverlay new GMapOverlay(markers); GMarkerGoogle marker new GMarkerGoogle( new PointLatLng(39.9042, 116.4074), GMarkerGoogleType.red_dot); marker.ToolTipText 设备 A\n状态在线; marker.ToolTipMode MarkerTooltipMode.OnMouseOver; markersOverlay.Markers.Add(marker); gmap.Overlays.Add(markersOverlay); // 折线层 GMapOverlay routesOverlay new GMapOverlay(routes); ListPointLatLng points new ListPointLatLng { new PointLatLng(39.9042, 116.4074), new PointLatLng(39.9142, 116.4174), new PointLatLng(39.9242, 116.4274) }; GMapRoute route new GMapRoute(points, route1); route.Stroke new Pen(Color.Blue, 3); routesOverlay.Routes.Add(route); gmap.Overlays.Add(routesOverlay); }逻辑说明每个GMapOverlay是一个独立图层标记和折线分开放便于后续单独清空或隐藏。GMarkerGoogleType决定标记图标样式red_dot是最常用的圆点。ToolTipMode设成OnMouseOver鼠标悬停才显示避免多个标记提示框互相遮挡。折线的Stroke用Pen控制颜色和线宽不设的话默认黑色细线在深色底图上几乎看不见。参数上要注意GMapRoute的构造函数第二个参数是图层内唯一名称重名会覆盖。坐标列表顺序就是绘制顺序不做自动排序。如果折线点特别多比如几千个 GPS 轨迹点直接全塞进去渲染会卡常见做法是按缩放层级抽稀或者用GMapRoute的分段加载。3. 瓦片缓存与离线部署GMap.net Demo 真正落地的关键3.1 瓦片是怎么被请求和缓存的GMap.NET 的瓦片机制是理解一切性能问题的钥匙。地图被切成一层层的正方形图片每个瓦片有x、y、zoom三个坐标。当你拖动或缩放地图时控件计算出当前视野需要哪些瓦片先去缓存目录找找不到再发 HTTP 请求。缓存目录默认在C:\Users\你的用户名\AppData\Local\GMap.NET\下面按地图提供商和层级分文件夹。这个机制决定了三件事。第一首次加载某个区域一定慢因为要下载。第二同一个区域第二次打开就快因为读本地文件。第三如果你换了MapProvider缓存不通用等于重新下载。很多人抱怨昨天还好好的今天地图加载不出来八成是缓存目录被清理了或者换了网络环境导致瓦片服务请求失败。GMaps.Instance.Mode控制的就是这个查找顺序。ServerAndCache是默认推荐值先缓存后网络。CacheOnly用于完全离线此时如果缓存里没有对应瓦片地图上就是空白格子不会报错这个静默失败很坑。ServerOnly基本不用除非你在调试瓦片服务本身。3.2 把缓存目录改到程序目录并预下载默认缓存目录在用户 AppData 下部署到客户机器上不好管理也不方便打包。常见做法是把缓存目录改到程序自己的目录下跟着程序走。// 在程序启动最早的地方执行早于任何地图控件创建 string cacheDir Path.Combine(AppDomain.CurrentDomain.BaseDirectory, MapCache); if (!Directory.Exists(cacheDir)) { Directory.CreateDirectory(cacheDir); } GMaps.Instance.PrimaryCache new GMap.NET.CacheProviders.SQLitePureImageCache { // 指定缓存数据库路径 }; // 或者用文件缓存方式指定目录 GMapProvider.CacheFolder cacheDir;逻辑说明GMap.NET 支持两种缓存后端SQLite 单文件缓存和文件目录缓存。SQLite 方式便于整体拷贝和清理文件方式便于直接看瓦片图片。CacheFolder是静态属性设置一次全局生效必须在创建地图控件之前设。设晚了控件已经用默认目录初始化过改不回来。预下载是离线部署的核心步骤。思路是遍历目标区域的瓦片坐标逐个触发下载。GMap.NET 没有现成的批量下载 API需要自己按瓦片编号循环。// 预下载指定经纬度范围、指定层级的瓦片 private void PreDownload(double minLat, double maxLat, double minLng, double maxLng, int minZoom, int maxZoom) { for (int zoom minZoom; zoom maxZoom; zoom) { // 经纬度转瓦片编号 int x1 (int)((minLng 180) / 360 * Math.Pow(2, zoom)); int x2 (int)((maxLng 180) / 360 * Math.Pow(2, zoom)); int y1 (int)((1 - Math.Log(Math.Tan(maxLat * Math.PI / 180) 1 / Math.Cos(maxLat * Math.PI / 180)) / Math.PI) / 2 * Math.Pow(2, zoom)); int y2 (int)((1 - Math.Log(Math.Tan(minLat * Math.PI / 180) 1 / Math.Cos(minLat * Math.PI / 180)) / Math.PI) / 2 * Math.Pow(2, zoom)); for (int x x1; x x2; x) { for (int y y1; y y2; y) { // 触发瓦片请求结果自动进缓存 var tile GMaps.Instance.GetImageFrom( GMapProviders.OpenStreetMap, x, y, zoom, out Exception ex); if (ex ! null) { Console.WriteLine($瓦片 {zoom}/{x}/{y} 失败{ex.Message}); } } } } }参数说明minZoom和maxZoom决定下载量每多一层瓦片数量大约翻四倍。一个城市范围下到 18 层瓦片数量可能到几十万张下载时间和磁盘占用都要提前评估。经纬度转瓦片编号的公式是 Web 墨卡托投影的标准算法纬度部分用了Math.Log和Math.Tan这是把球面纬度映射到平面 y 坐标的关键写错会导致下载区域偏移。注意预下载会向瓦片服务发起大量请求务必控制并发和频率加Thread.Sleep或限流否则容易被封。生产环境建议用自建瓦片服务或购买商业瓦片不要对公共瓦片服务做大规模抓取。3.3 离线模式下的显示验证预下载完成后把GMaps.Instance.Mode切成CacheOnly断网测试。如果地图能正常显示之前下载过的区域说明缓存生效。如果出现空白格子按这个顺序排查缓存目录路径是否和下载时一致、MapProvider是否和下载时一致、缩放层级是否在下载范围内。这三个条件缺一个缓存就命中不了。验证时可以打开缓存目录看文件结构文件缓存方式下会看到按zoom分文件夹、按x分文件名的图片。SQLite 方式下用数据库工具打开看Tiles表。看到文件存在但地图不显示多半是MapProvider的哈希值变了不同 provider 的缓存键不一样。4. 坐标、投影与性能GMap.net Demo 里最容易翻车的三件事4.1 经纬度和屏幕坐标的相互转换地图上打点、画线、响应鼠标点击都绕不开坐标转换。GMap.NET 提供FromLatLngToLocal和FromLocalToLatLng两个方法前者把经纬度转成控件内的像素坐标后者反过来。// 经纬度 - 控件像素坐标 PointLatLng latLng new PointLatLng(39.9042, 116.4074); GPoint local gmap.FromLatLngToLocal(latLng); Console.WriteLine($像素坐标{local.X}, {local.Y}); // 控件像素坐标 - 经纬度 GPoint mousePoint new GPoint(e.X, e.Y); PointLatLng clicked gmap.FromLocalToLatLng((int)mousePoint.X, (int)mousePoint.Y); Console.WriteLine($点击位置经纬度{clicked.Lat}, {clicked.Lng});逻辑说明FromLatLngToLocal返回的是相对于控件左上角的像素坐标不是屏幕坐标。如果你要弹右键菜单还得加上控件在窗体上的偏移。FromLocalToLatLng常用于鼠标点击拾取比如点击地图获取该点经纬度再查数据库。这两个方法在拖动和缩放过程中结果会变所以不要在初始化时算一次就存起来要在需要时实时算。常见翻车点把GPoint的X、Y当成经纬度用。GPoint是像素坐标PointLatLng才是经纬度两者类型不同但都是两个数字新手容易混。另一个坑是缩放后没有重新计算标记位置导致标记漂移。GMap.NET 的标记是绑定经纬度的控件会自动重算但如果你手动用像素坐标画图就必须在OnMapZoomChanged事件里重绘。4.2 大量标记的性能优化设备监控场景动辄几百上千个标记直接往Overlay里塞会明显卡顿。优化思路有三条减少标记数量、降低单个标记开销、按视野裁剪。减少标记数量靠聚合。同一区域内多个设备合并成一个带数字的聚合标记放大到一定层级再展开。GMap.NET 没有内置聚合需要自己按网格分组。降低单个标记开销靠复用图标不要每个标记都 new 一个Bitmap用静态图片资源。按视野裁剪是在OnMapDrag或OnMapZoomChanged里只保留当前视野内的标记视野外的从 Overlay 移除。// 按当前视野裁剪标记避免全量渲染 private void RefreshMarkersInView() { markersOverlay.Markers.Clear(); RectLatLng view gmap.ViewArea; foreach (var device in allDevices) { if (view.Contains(device.Lat, device.Lng)) { var m new GMarkerGoogle( new PointLatLng(device.Lat, device.Lng), GMarkerGoogleType.blue_dot); m.Tag device.Id; markersOverlay.Markers.Add(m); } } }参数说明gmap.ViewArea返回当前视野的经纬度矩形Contains判断点是否在矩形内。这个刷新要绑定到地图的OnMapDrag和OnMapZoomChanged事件上但事件触发很频繁要加节流比如用Timer延迟 200 毫秒再执行避免拖动过程中反复重算。4.3 地图提供商的选择与切换GMapProviders里预置了很多地图源但可用性和访问速度差异很大。选 provider 要考虑三件事瓦片风格是否适合业务、访问是否稳定、是否有使用条款限制。内网部署建议自建瓦片服务用GMapProvider的自定义实现指向内网地址。// 自定义瓦片源指向内网服务 public class InternalMapProvider : GMapProvider { public override PureImage GetTileImage(GPoint pos, int zoom) { string url $http://内网地址/tiles/{zoom}/{pos.X}/{pos.Y}.png; return GetTileImageUsingHttp(url); } // 其余抽象成员按基类要求实现 }逻辑说明继承GMapProvider需要实现GetTileImage和若干抽象属性核心就是拼出瓦片 URL 然后调GetTileImageUsingHttp。内网服务返回的图片格式要和声明一致png 和 jpg 混用会导致部分瓦片解码失败。切换 provider 后缓存不通用要重新预下载。5. 避坑与排查GMap.net Demo 跑不起来时先看这几条5.1 地图一片空白没有任何瓦片现象控件显示出来了但地图区域是灰白格子或者纯色没有底图。原因通常是瓦片请求全部失败。可能是UserAgent没设被服务端拒绝可能是网络不通可能是MapProvider选了一个已经失效的源。解决先设UserAgent再换GMapProviders.OpenStreetMap测试如果还不行就在GetTileImage里打日志看 HTTP 状态码。内网环境要确认代理设置GMap.NET 默认走系统代理。5.2 拖动地图时标记位置漂移现象地图拖动后之前打的标记跑到错误的位置。原因是你用了像素坐标而不是经纬度来定位标记。GMap.NET 的GMarkerGoogle构造函数接收的是PointLatLng只要传的是经纬度控件会自动跟随地图变换。如果你自己画图或者用FromLatLngToLocal算出来的像素坐标去定位拖动后必须重算。解决标记一律用经纬度创建不要缓存像素坐标。5.3 缓存目录越来越大磁盘被占满现象程序运行一段时间后缓存目录几个 GB。原因是瓦片缓存只增不减GMap.NET 没有自动清理机制。解决定期清理旧瓦片或者限制缓存大小。可以在程序启动时检查缓存目录大小超过阈值就删除最旧的层级文件夹。更稳妥的做法是只预下载业务需要的层级不要开放过大的MaxZoom。5.4 缩放层级设太宽导致请求量爆炸现象用户滚轮缩放时程序卡顿网络请求暴增。原因是MinZoom设到 1、MaxZoom设到 20用户一次缩放跨越多个层级每层都要请求新瓦片。解决根据业务需要限制缩放范围比如只允许 10 到 16 层。同时开启gmap.Manager.BoostCacheEngine之类的缓存加速选项减少重复请求。5.5 多线程更新标记导致界面卡死或异常现象后台线程收到设备位置更新直接往Overlay里加标记程序崩溃或界面无响应。原因是 GMap.NET 的控件不是线程安全的所有 UI 操作必须在主线程。解决用Invoke或BeginInvoke把标记更新切回主线程或者用ConcurrentQueue缓存更新在主线程的Timer里批量处理。// 后台线程更新标记的正确姿势 this.Invoke(new Action(() { markersOverlay.Markers.Add(new GMarkerGoogle( new PointLatLng(lat, lng), GMarkerGoogleType.green_dot)); gmap.Refresh(); }));6. 把 GMFlow 思路用起来轨迹回放与动态刷新的一个实用技巧轨迹回放是设备监控里很典型的需求GMFlow这个词如果指的是地图上的流动效果那核心就是按时间序列逐点更新标记位置并画线。我一般用一个Timer驱动每次取一个轨迹点更新标记位置同时往折线里追加点。这里有个技巧不要每次清空重画整条线而是维护一个GMapRoute对象往它的Points里追加然后调gmap.Refresh()。清空重画在点数多的时候会闪屏。private GMapRoute trackRoute; private GMarkerGoogle trackMarker; private int trackIndex 0; private ListPointLatLng trackPoints; // 预加载的轨迹点 private void StartReplay() { trackRoute new GMapRoute(new ListPointLatLng(), track); trackRoute.Stroke new Pen(Color.Red, 3); var overlay new GMapOverlay(track); overlay.Routes.Add(trackRoute); gmap.Overlays.Add(overlay); trackMarker new GMarkerGoogle(trackPoints[0], GMarkerGoogleType.red_dot); overlay.Markers.Add(trackMarker); var timer new System.Windows.Forms.Timer { Interval 500 }; timer.Tick (s, e) { if (trackIndex trackPoints.Count) { timer.Stop(); return; } var p trackPoints[trackIndex]; trackMarker.Position p; // 移动标记 trackRoute.Points.Add(p); // 追加轨迹点 gmap.Position p; // 地图跟随 gmap.Refresh(); }; timer.Start(); }逻辑说明trackMarker.Position直接赋值就能移动标记不用删了重建。trackRoute.Points.Add追加点后折线自动延长。gmap.Position p让地图中心跟随标记形成回放效果。Interval控制回放速度500 毫秒一个点适合演示实际回放可以按时间戳差值动态调整。参数上要注意trackPoints如果来自 GPS 原始数据可能有漂移点回放前要做平滑滤波否则标记会跳来跳去。另外gmap.Refresh()调用频率不要太高Interval低于 100 毫秒时可以考虑合并刷新。回放结束后记得把timer释放否则重复点击开始会叠加多个定时器速度越来越快这个坑我踩过。最后说个习惯每次改完地图相关代码我都会断网跑一遍CacheOnly模式确认离线可用再提交。地图这东西联网时一切正常一到客户内网就各种空白后悔药没得吃。希望帮到你。本文还有配套的精品资源点击获取