v6.0 Upgrade Guide

SkiaSharp compatibility

Mapsui is compiled against SkiaSharp 3.119.4. MAUI applications may resolve the supported SkiaSharp 4.151.2 release instead; this combination is covered by a packaged-consumer test, including native loading and the RichTextKit/HarfBuzz callout path. Keep explicit SkiaSharp, SkiaSharp.Views.*, SkiaSharp.HarfBuzz, and HarfBuzzSharp references on the same release train selected by the SkiaSharp release in such applications.

Avalonia 12.1 depends on SkiaSharp 3.119.4 but also supports SkiaSharp 4 when the application references it explicitly (see AvaloniaUI/Avalonia#21696). The Avalonia 12 samples run this way on SkiaSharp 4.151.2. Keep SkiaSharp.HarfBuzz, HarfBuzzSharp, and HarfBuzzSharp.NativeAssets.Linux on the matching release train; Avalonia still pulls in the 8.x Linux native asset, which does not match the 14.x managed HarfBuzzSharp.

On Windows, Avalonia 12.1's Vulkan rendering mode crashes with SkiaSharp 4 (an access violation in VulkanDevice.Create), while ANGLE works. If you use SkiaSharp 4, leave Win32RenderingMode.Vulkan out of Win32PlatformOptions.RenderingMode. Mapsui will target SkiaSharp 4 directly once all supported UI frameworks work with it.

By compile error

Below is a list of compile errors that you could encounter when upgrading from Mapsui V5 to V6. Please inform us if you run into compile errors that are not in this list.

New API in v6

These properties are new in v6 and available regardless of which renderer you use.

LabelStyle.TextAlignment

A new TextAlignment property (type: Alignment) controls how text lines are aligned within the label box. This is separate from HorizontalAlignment, which positions the label box relative to the feature point.

new LabelStyle
{
    TextAlignment = Alignment.Right, // text content alignment within the box
    HorizontalAlignment = LabelStyle.HorizontalAlignmentEnum.Center, // box position relative to point
}

Default: Alignment.Left. See also the Breaking changes in the experimental renderer section below.

CalloutStyle.TitleTextAlignment and CalloutStyle.SubtitleTextAlignment

New Alignment properties on CalloutStyle let you align title and subtitle text independently within the callout balloon. Both default to Alignment.Left.

new CalloutStyle
{
    TitleTextAlignment = Alignment.Right,
    SubtitleTextAlignment = Alignment.Center,
}

Font.FontSource

A new FontSource property on Font lets you load a custom typeface from a URI or embedded resource instead of relying on a system-installed font family.

new LabelStyle
{
    Font = new Font
    {
        FontSource = new FontSource("embedded://MyAssembly/Fonts/NotoSansArabic.ttf"),
        Size = 16
    }
}

The font bytes are fetched once per unique source and cached in RenderService.FontSourceCache for the lifetime of the map. See the FontSource documentation for details.

Note: Font.FontSource is only rendered by Mapsui.Experimental.Rendering.Skia. The standard renderer (Mapsui.Rendering.Skia) ignores it and falls back to the system font.

New capabilities in the experimental renderer

The experimental renderer (Mapsui.Experimental.Rendering.Skia) adds the following rendering capabilities that are not available in the standard renderer.

Right-to-left and bidirectional text

The experimental renderer correctly shapes and visually orders RTL text (Arabic, Hebrew, etc.) using HarfBuzz glyph shaping and UAX#9 bidi reordering via RichTextKit. The standard renderer does not support RTL.

To render Arabic text correctly:

new LabelStyle
{
    Text = "مرحبا بالعالم",
    Font = new Font { FontSource = new FontSource("embedded://..."), Size = 16 },
    TextAlignment = Alignment.Right,
}

Unicode line breaking (UAX#14)

Word wrapping in the experimental renderer uses the Unicode Line Break Algorithm (UAX#14) for correct break-point detection across CJK, Arabic, and other scripts. The standard renderer uses a simpler space/character-based split.

Custom fonts (Font.FontSource)

As described above, Font.FontSource is only applied when using the experimental renderer.

Two-step rendering architecture

The experimental renderer separates drawing into two phases:

1. Prepare (background thread) — creates platform resources (paths, paints, decoded rasters).
2. Draw (render thread) — blits pre-created resources onto the canvas.

This improves frame-rate consistency on complex maps. There is no API change for users; the renderer handles the split internally.

Breaking changes in the experimental renderer

The experimental renderer (Mapsui.Experimental.Rendering.Skia) introduces stricter separation between two concerns that were previously conflated in LabelStyle.HorizontalAlignment:

1. Box anchor — where the label box is positioned relative to the feature point.
2. Text alignment — how text lines are aligned inside the label box.

In v5, HorizontalAlignment controlled both. In v6 the experimental renderer separates these into two properties:

Purpose	Property	Type
Box anchor (position relative to point)	LabelStyle.HorizontalAlignment	HorizontalAlignmentEnum
Text alignment within the box	LabelStyle.TextAlignment	Alignment

What to do

If you were using the experimental renderer and relied on HorizontalAlignment to also center or right-align text inside a multi-line label box, add an explicit TextAlignment setting:

// v5 (experimental renderer): HorizontalAlignment controlled both box anchor and text alignment
new LabelStyle
{
    HorizontalAlignment = LabelStyle.HorizontalAlignmentEnum.Center,
}

// v6: set TextAlignment explicitly for within-box text alignment
new LabelStyle
{
    HorizontalAlignment = LabelStyle.HorizontalAlignmentEnum.Center,
    TextAlignment = Alignment.Center,
}

Default value

TextAlignment defaults to Alignment.Left. For RTL scripts (Arabic, Hebrew, etc.) set it to Alignment.Right, or use Alignment.Auto to have the renderer detect direction from the text content automatically.

Non-experimental renderer

The non-experimental renderer (Mapsui.Rendering.Skia) is unchanged — HorizontalAlignment continues to control both box anchor and within-box text alignment as it did in v5.