Azure Maps Rendering：图钉名称含单引号报错及特殊字符兼容问题

1. 单引号的处理方式 #

问题根源是Azure Maps静态地图API在解析图钉标签时，单引号被用作标签的包裹分隔符，导致标签内的单引号提前闭合包裹结构，进而破坏后续经纬度的解析逻辑。

解决方法是将标签中的单个单引号替换为两个连续单引号（这是字符串解析场景中通用的单引号转义规则），修改代码如下：

public async Task<byte[]> GetMapThumbnailAsync(string? name, double longitude, double latitude)
{
    var pushPins = new List<ImagePushpinStyle>();
    if (!string.IsNullOrEmpty(name))
    {
        // 转义标签中的单引号
        var escapedName = name.Replace("'", "''");
        var position = new PushpinPosition(longitude, latitude, escapedName);
        var pushpinSet = new ImagePushpinStyle(new List<PushpinPosition>() { position })
        {
            PushpinScaleRatio = 0.8,
            PushpinColor = Color.Red,
            LabelColor = Color.Green,
            LabelScaleRatio = 10
        };
        pushPins.Add(pushpinSet);
    }
    // 后续业务逻辑...
}

传入"Dave's home"时，转义后变为"Dave''s home"，API会正确识别为包含单引号的标签内容，不会破坏经纬度的解析格式。

2. 其他可能导致解析失败的字符 #

除单引号外，以下字符也会干扰API的参数解析逻辑，需要提前处理：

• 逗号（,）：API可能将逗号视为多个图钉参数的分隔符，导致标签被截断
• 双引号（"）：若API内部用双引号处理字符串结构，双引号会导致包裹逻辑异常
• 反斜杠（\）：会被当作转义符，破坏原有字符串的解析规则
• 控制字符：如换行符（\n）、制表符（\t）等非打印字符，会打乱参数的文本格式
• 百分号（%）：未正确URL编码时，会被误认为是URL转义标记，引发解析错误

这类字符的问题本质是：Azure Maps静态地图API的图钉参数基于固定文本格式构建，当标签包含解析引擎视为语法标记的字符时，会直接破坏参数结构，导致经纬度或标签解析失败。

内容的提问来源于stack exchange，提问作者David Thielen