Brutile

项目地址： https://github.com/BruTile/BruTile

NuGet： BruTile 6.0.0 / BruTile.MbTiles 6.0.0（net8.0 / net9.0，截至 2026-10）

官方文档： https://github.com/BruTile/BruTile

许可证： Apache-2.0

概述

BruTile 是一个只管「瓦片」的 .NET 库：给定视口范围与分辨率，算出需要哪些瓦片，再去对应服务把瓦片字节取回来。它不做渲染、不含 UI，瓦片最终由 Mapsui、SharpMap、ArcBruTile 等地图组件显示。这种职责划分让 BruTile 可以同时支撑 WPF、MAUI、Blazor、ASP.NET 等多种宿主，也是它在 .NET 地图栈中长期作为底座的原因。

• 瓦片方案（schema）：Web 墨卡托全球网格、WMTS、TMS、WMS-C 等组织的分辨率与瓦片索引映射
• 瓦片源：HTTP 瓦片服务（XYZ/OSM、ArcGIS、Bing 等）、MBTiles 离线文件、文件系统瓦片缓存
• 视口计算：ITileSchema.GetTileInfos(extent, resolution) 求当前需要渲染的瓦片集合
• 缓存：内存缓存与持久化缓存（MBTiles、文件系统）可组合
• 坐标系约定：默认 Web 墨卡托（EPSG:3857），OSM 与 TMS 的 y 轴方向不同，需显式选择

版本提示：BruTile 6.0.0 只发布 net8.0 / net9.0 目标。需要 netstandard2.0 的场景（例如 .NET Framework、SharpMap 1.2）只能用 5.0.6 或更早版本，详见下方版本对照表。

环境准备

安装

bashCopy code
# 在线瓦片（HTTP 服务）
dotnet add package BruTile --version 6.0.0

# 离线 MBTiles 需要额外的包
dotnet add package BruTile.MbTiles --version 6.0.0

# 需要挂在 Mapsui 上时
dotnet add package Mapsui --version 5.1.0

powershellCopy code
Install-Package BruTile -Version 6.0.0

验证

csharpCopy code
using BruTile;
using BruTile.Predefined;

var schema = new GlobalSphericalMercator();
Console.WriteLine(schema.Resolutions.Count);   // 默认 0..19 级共 20 个分辨率
var tileInfos = schema.GetTileInfos(
    new Extent(-20037508, -20037508, 20037508, 20037508), 156543.03392804097);
Console.WriteLine(tileInfos.Count());          // 0 级应只有 1 张

bashCopy code
dotnet run

版本与目标框架对照

BruTile.Desktop、BruTile.Desktop.DbCache 这两个包名在 4.0 之后已不存在，旧代码里的 using BruTile.Desktop 需要改命名空间。

核心 API

TileSchema 与分辨率

csharpCopy code
using BruTile;
using BruTile.Predefined;

// 全球 Web 墨卡托，默认 0-19 级；y 轴默认 OSM 约定
var schema = new GlobalSphericalMercator(minZoomLevel: 0, maxZoomLevel: 18);

// 自定义瓦片方案
var custom = new TileSchema
{
    Name = "MyTiles",
    Srs = "EPSG:3857",
    Extent = new Extent(-20037508, -20037508, 20037508, 20037508),
    YAxis = YAxis.OSM,
    Format = "image/png",
};
custom.Resolutions.Add(0, new Resolution(0, 156543.03392804097, 256, 256));
custom.Resolutions.Add(1, new Resolution(1, 78271.51696402048, 256, 256));

HttpTileSource

csharpCopy code
using BruTile;
using BruTile.Predefined;
using BruTile.Web;

// 自定义 XYZ 服务；{s} 为子域占位，传 serverNodes 展开
var source = new HttpTileSource(
    new GlobalSphericalMercator(0, 18),
    "https://{s}.tile.example.com/{z}/{x}/{y}.png",
    new[] {"a", "b", "c"},
    name: "example");

using var http = new HttpClient();
var extent = new Extent(12900000, 4800000, 13000000, 4900000);
double resolution = extent.Width / 800;          // 800 像素宽的视口

foreach (TileInfo info in source.Schema.GetTileInfos(extent, resolution))
{
    byte[]? png = await source.GetTileAsync(http, info);   // 6.x：显式传 HttpClient
    Console.WriteLine($"{info.Index.Level}/{info.Index.Col}/{info.Index.Row}: {png?.Length ?? 0} bytes");
}

HttpClient 按应用生命周期创建一次即可，每次请求 new 一个会耗尽 socket；这是 IHttpTileSource 把客户端作为参数传进来的主要原因。

KnownTileSources

csharpCopy code
using BruTile.Predefined;

var osm     = KnownTileSources.Create();                                  // 默认 OpenStreetMap
var cycle   = KnownTileSources.Create(KnownTileSource.OpenCycleMap);
var satellite = KnownTileSources.Create(KnownTileSource.BingAerial, apiKey: "YOUR_BING_KEY");
var noneApi = KnownTileSources.Create(KnownTileSource.EsriWorldTopo);

KnownTileSource 覆盖 OSM/OpenCycleMap、Bing（Aerial/Hybrid/Roads 及其 Staging 变体）、Stamen 系列、Esri World 系列、BKG（德国）、Here 系列；需要密钥的服务通过 apiKey 传入。Create 还可传 minZoomLevel / maxZoomLevel 限制范围，但每个服务内部会再按自身能力截断（例如 OSM 最高 18 级、Bing 从 1 级起），实际可用级别以返回的 Schema.Resolutions 为准。

MBTiles 离线瓦片

csharpCopy code
using BruTile;
using BruTile.MbTiles;
using SQLite;

var connection = new SQLiteConnectionString("data/world.mbtiles", SQLiteOpenFlags.ReadOnly);
var mbTiles = new MbTilesTileSource(connection);

var tile = await mbTiles.GetTileAsync(new TileInfo {Index = new TileIndex(0, 0, 0)});
Console.WriteLine(tile?.Length);

SQLiteConnectionString 来自 sqlite-net，6.0.0 的 MBTiles 包通过 SQLitePCLRaw 3.x 带原生库；发布到 AOT/裁剪环境时必须显式保留 SQLite 原生库，否则运行期报「无法加载 sqlite3」。

典型工作流

把 OSM 在线底图和一个 MBTiles 离线图层组合起来，先判断视口需要哪些瓦片，再分别取图并统计缓存命中：

输入：视口范围（Web 墨卡托米）、屏幕像素宽度、MBTiles 文件 输出：控制台打印每张瓦片的来源与字节数

1. 用 GlobalSphericalMercator 建立方案，按视口宽 / 像素宽算出分辨率
2. 用 GetTileInfos(extent, resolution) 得到需要的瓦片列表
3. MBTiles 优先，缺失时回落到 HTTP 源
4. 复用同一个 HttpClient

csharpCopy code
using BruTile;
using BruTile.MbTiles;
using BruTile.Predefined;
using SQLite;

var extent = new Extent(12957000, 4852000, 12960000, 4855000);
const int viewportWidth = 1024;
double resolution = extent.Width / viewportWidth;

var http = new HttpClient();
var osm = KnownTileSources.Create(KnownTileSource.OpenStreetMap);

var offline = new MbTilesTileSource(
    new SQLiteConnectionString("data/region.mbtiles", SQLiteOpenFlags.ReadOnly));

int fromCache = 0, fromWeb = 0;
foreach (TileInfo info in osm.Schema.GetTileInfos(extent, resolution))
{
    byte[]? bytes = await offline.GetTileAsync(info);
    if (bytes is {Length: > 0})
    {
        fromCache++;
        continue;
    }

    bytes = await osm.GetTileAsync(http, info);
    if (bytes is {Length: > 0}) fromWeb++;
}

Console.WriteLine($"cache={fromCache} web={fromWeb}");

检查点：瓦片数量随缩放级别呈 4 倍增长，fromWeb 异常大通常说明 MBTiles 的 y 轴约定与 schema 不一致（OSM 与 TMS 相反），可在 MbTilesTileSource 构造时显式传 schema 验证。

最佳实践

1. 复用 HttpClient 与 TileSource：瓦片源与 HttpClient 都是无状态可复用的对象，放在字段或 DI 单例里
2. 明确 y 轴约定：OSM 原点在左上、TMS 在左下；瓦片行列错位错位一整屏，先把 YAxis 对齐再排查网络
3. 缓存分两层：内存缓存应对快速平移缩放，MBTiles 或文件系统缓存应对离线与省钱；构造 HttpTileSource 时传 persistentCache
4. 限制缩放级别：GlobalSphericalMercator(min, max) 与服务实际级别一致，超出范围只会拿到 404
5. 尊重版权与速率限制：OSM 等公共服务有使用政策，生产环境用商业或自建瓦片服务，Attribution 要显示出来
6. MBTiles 只读打开：SQLiteOpenFlags.ReadOnly + 单例连接，避免多线程写锁
7. 按目标框架选版本：net8+ 用 6.0.0；netstandard2.0 或 SharpMap 1.2 场景降到 5.0.6/4.0.0

常见问题

AI 使用建议

• 执行环境：dotnet add package / dotnet build / dotnet run 在终端中执行，首次 restore 需访问 NuGet。
• 先探测版本：dotnet list package 确认 BruTile 是 6.0.0 还是 5.x——两者的 GetTileAsync 签名不同，写代码前必须确认；目标框架须为 net8.0/net9.0 才能用 6.0.0。
• 验证产物：先跑「schema + GetTileInfos 计数」的最小用例（0 级应为 1 张瓦片），再验证网络取图；取图结果检查字节长度大于 0，不要只看是否抛异常。
• 网络与权限：抓取第三方瓦片服务前确认其使用政策与是否需要 key；不要在示例里写死真实密钥。
• 失败信号：404 先查模板与级别；行列错位查 YAxis；DllNotFoundException/无法加载 sqlite3 查 MBTiles 原生库复制。
• 排错顺序：先离线验证 schema 计算，再接网络层，最后接 UI；把三层分开验证能快速定位是坐标、网络还是渲染问题。

相关技能

• mapsui — 现代跨平台 .NET 地图组件，直接用 BruTile 作瓦片源：../mapsui/SKILL.md
• sharpmap — 旧版渲染库，通过 SharpMap.Layers.BruTile 使用 BruTile（版本受限）：../sharpmap/SKILL.md
• nettopologysuite — 空间几何与坐标，常与瓦片坐标换算配合：../nettopologysuite/SKILL.md
• projnet4geoapi — 坐标变换，处理非 Web 墨卡托瓦片时使用：../projnet4geoapi/SKILL.md
• leaflet — Web 端瓦片地图，便于对照 XYZ 模板与 y 轴约定：../leaflet/SKILL.md

参考资源

• 源码与示例（Samples/BruTile.GettingStarted）：https://github.com/BruTile/BruTile
• 预定义瓦片源定义：https://github.com/BruTile/BruTile/blob/master/BruTile/Predefined/KnownTileSources.cs
• NuGet：https://www.nuget.org/packages/BruTile
• MBTiles 规范：https://github.com/mapbox/mbtiles-spec
• OSM 瓦片使用政策：https://operations.osmfoundation.org/policies/tiles/