Map: document namespace conflict between Controls.Maps.Map and ApplicationModel.Map

[PureWeen]

Summary

The Map documentation does not mention a common compile error caused by an ambiguous reference between Microsoft.Maui.Controls.Maps.Map and Microsoft.Maui.ApplicationModel.Map. Both are commonly imported via implicit usings, and the conflict is not obvious from the error message.

Why it matters

When a developer adds the Maps NuGet package and writes new Map() or uses <Map> in XAML, they get:

error CS0104: 'Map' is an ambiguous reference between 'Microsoft.Maui.Controls.Maps.Map' and 'Microsoft.Maui.ApplicationModel.Map'

This is confusing because ApplicationModel.Map (used for Map.OpenAsync to launch the native maps app) is auto-imported and invisible. Developers unfamiliar with C# namespace aliases may not know how to resolve it.

What should be documented

Add a note early in the Map setup documentation:

Note: Microsoft.Maui.Controls.Maps.Map can conflict with Microsoft.Maui.ApplicationModel.Map (which provides Map.OpenAsync for launching the native maps app). If you get an ambiguous reference error, add a namespace alias:

// C# — add at the top of files that use the Map control
using Map = Microsoft.Maui.Controls.Maps.Map;

<!-- XAML — use a namespace prefix -->
<ContentPage xmlns:maps="clr-namespace:Microsoft.Maui.Controls.Maps;assembly=Microsoft.Maui.Controls.Maps">
    <maps:Map x:Name="map" />
</ContentPage>

Also note that Windows does not have native Map support in Microsoft.Maui.Controls.Maps — Windows apps must use CommunityToolkit.Maui.Maps instead.

Suggested location

docs/user-interface/controls/map.md — in the setup/getting-started section, before the first code example