v6.0 Upgrade Guide

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.