Index of every page on this site: llms.txt
All skills
davidortinau avatar

/maui-maps

@79bb4bf
Run it yourself

Guidance for adding map controls, pins, polygons, polylines, geocoding, Google Maps API key configuration, and platform setup in .NET MAUI apps using Microsoft.Maui.Controls.Maps. USE FOR: "add map", "map control", "map pins", "polygons on map", "polylines", "geocoding", "Google Maps API key", "Microsoft.Maui.Controls.Maps", "map setup", "reverse geocoding", "map region". DO NOT USE FOR: getting device GPS coordinates (use maui-geolocation), custom drawing overlays (use maui-graphics-drawing), or location permissions only (use maui-permissions).

Use this Skill: https://skilld.dev/gh/davidortinau/maui-skills/maui-maps

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈141 tokens for metadata: the name and description. ≈997 when used: this file. ≈1.4k more on demand in 1 file.

Description uses 7.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈563 characters, or 7.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

.NET MAUI Maps

Common gotchas

Issue Fix
Map is blank on Android Google Maps API key missing or wrong in AndroidManifest.xml
Map crashes on startup .UseMauiMaps() not called in MauiProgram.cs
Map type ambiguous Conflicts with Microsoft.Maui.ApplicationModel.Map — add namespace alias
Map doesn't show on Windows Windows has no native support — must use CommunityToolkit.Maui.Maps
User location dot missing IsShowingUser="True" set but location permission not granted
Android 11+ can't launch external map app Missing <queries> for geo scheme in manifest

⚠️ Name conflict — always alias

Microsoft.Maui.Controls.Maps.Map conflicts with Microsoft.Maui.ApplicationModel.Map. This causes confusing compile errors.

// ✅ Correct — explicit alias
using Map = Microsoft.Maui.Controls.Maps.Map;
<!-- ✅ Correct — namespace prefix in XAML -->
xmlns:maps="clr-namespace:Microsoft.Maui.Controls.Maps;assembly=Microsoft.Maui.Controls.Maps"
<maps:Map ... />

<!-- ❌ Wrong — bare <Map> is ambiguous -->
<Map ... />

Platform setup pitfalls

Android — API key must be inside <application>

<!-- ✅ Correct -->
<application ...>
  <meta-data android:name="com.google.android.geo.API_KEY"
             android:value="YOUR_GOOGLE_MAPS_KEY" />
</application>

<!-- ❌ Outside <application> — key is silently ignored -->

⚠️ Also required: Google Play Services version meta-data and <queries> for geo scheme on API 30+ (see references/maps-api.md).

iOS / Mac Catalyst

⚠️ Without NSLocationWhenInUseUsageDescription in Info.plist, location permission is denied without prompt.

Windows — no native support

Must add CommunityToolkit.Maui.Maps + Bing key. Use conditional package reference and #if WINDOWS for setup.

MauiProgram.cs — don't forget UseMauiMaps

// ✅ Required — without this, Map control throws at runtime
builder.UseMauiMaps();

// ❌ Forgetting this causes "No registered handler for Map" crash

Performance tips

  • ⚠️ Don't add hundreds of pins directly — use ItemsSource with data binding for large pin sets.
  • Set initial region with MoveToRegion() to avoid the default world view zoom animation.
  • Avoid frequent MoveToRegion() calls — each triggers a map animation; debounce if driven by data changes.

Data-bound pins — do this for dynamic data

<!-- ✅ Correct — data-bound pins for dynamic collections -->
<maps:Map ItemsSource="{Binding Locations}">
    <maps:Map.ItemTemplate>
        <DataTemplate>
            <maps:Pin Label="{Binding Name}"
                      Address="{Binding Description}"
                      Location="{Binding Position}" />
        </DataTemplate>
    </maps:Map.ItemTemplate>
</maps:Map>

<!-- ❌ Wrong — manually adding pins in code-behind for data-driven scenarios -->

Decision framework

Need Approach
Basic map with pins Map control + Pins.Add() or ItemsSource binding
Map with shapes MapElements — Polygon, Polyline, Circle
Address → coordinates Geocoding.Default.GetLocationsAsync(address)
Coordinates → address Geocoding.Default.GetPlacemarksAsync(lat, lon)
Custom map overlays Use handlers to access native map APIs
Windows support Must add CommunityToolkit.Maui.Maps + Bing key

Quick checklist

  • NuGet: Microsoft.Maui.Controls.Maps added
  • .UseMauiMaps() called in MauiProgram.cs
  • Android: Google Maps API key inside <application> in AndroidManifest.xml
  • Android: Google Play Services version meta-data present
  • Android 11+: <queries> for geo scheme added
  • iOS/Mac: NSLocationWhenInUseUsageDescription in Info.plist
  • Windows: CommunityToolkit.Maui.Maps + Bing Maps key (conditional)
  • Namespace alias added to avoid Map type conflict

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides configuration and implementation guidance for .NET MAUI Maps. It does not contain any executable code, network exfiltration, or malicious instructions. The API key references provided are standard placeholders for developer configuration.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1 file scanned · No issues

Signed by skilld at 79bb4bf. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 8 months ago

README badge

README badge for davidortinau/maui-skills/maui-maps