{"id":1891,"date":"2026-07-30T13:00:00","date_gmt":"2026-07-30T18:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=1891"},"modified":"2026-03-07T03:50:18","modified_gmt":"2026-03-07T08:50:18","slug":"maui-deep-linking","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/maui-deep-linking\/","title":{"rendered":".NET MAUI Deep Linking: Implementation Guide"},"content":{"rendered":"\n

.NET MAUI (Multi-platform App UI) is the successor to Xamarin.Forms. It uses a single C# codebase for iOS, Android, macOS, and Windows, with platform-specific code isolated in the Platforms\/<\/code> directory. Deep linking in MAUI follows the same native patterns (Universal Links on iOS, App Links on Android) but integrates with MAUI's Shell navigation and dependency injection.<\/p>\n\n\n\n

For Xamarin.Forms (legacy), see Xamarin deep linking: cross-platform setup<\/a>. For the cross-platform overview, see cross-platform deep linking guide for 2026<\/a>.<\/p>\n\n\n\n

iOS Configuration<\/h2>\n\n\n\n

1. Associated Domains Entitlement<\/h3>\n\n\n\n

Create or update Platforms\/iOS\/Entitlements.plist<\/code>:<\/p>\n\n\n\n

<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-\/\/Apple\/\/DTD PLIST 1.0\/\/EN"\n  "http:\/\/www.apple.com\/DTDs\/PropertyList-1.0.dtd">\n<plist version="1.0">\n<dict>\n    <key>com.apple.developer.associated-domains<\/key>\n    <array>\n        <string>applinks:yourdomain.com<\/string>\n    <\/array>\n<\/dict>\n<\/plist>\n<\/code><\/pre>\n\n\n\n
Reference it in your .csproj<\/code>:<\/p>\n\n\n\n
<PropertyGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">\n    <CodesignEntitlements>Platforms\/iOS\/Entitlements.plist<\/CodesignEntitlements>\n<\/PropertyGroup>\n<\/code><\/pre>\n\n\n\n
2. AASA File<\/h3>\n\n\n\n
Host at https:\/\/yourdomain.com\/.well-known\/apple-app-site-association<\/code>:<\/p>\n\n\n\n
{\n  "applinks": {\n    "details": [{\n      "appIDs": ["TEAMID.com.yourcompany.yourapp"],\n      "components": [\n        { "\/": "\/products\/*" },\n        { "\/": "\/offers\/*" },\n        { "\/": "\/referral\/*" }\n      ]\n    }]\n  }\n}\n<\/code><\/pre>\n\n\n\n
Get your Team ID from Apple Developer account<\/a> under Membership Details.<\/p>\n\n\n\n
3. Handle Universal Links<\/h3>\n\n\n\n
In Platforms\/iOS\/AppDelegate.cs<\/code>:<\/p>\n\n\n\n
using Foundation;\nusing UIKit;\n\n[Register("AppDelegate")]\npublic class AppDelegate : MauiUIApplicationDelegate\n{\n    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();\n\n    [Export("application:continueUserActivity:restorationHandler:")]\n    public bool ContinueUserActivity(\n        UIApplication application,\n        NSUserActivity userActivity,\n        UIApplicationRestorationHandler completionHandler)\n    {\n        if (userActivity.ActivityType == NSUserActivityType.BrowsingWeb\n            && userActivity.WebPageUrl != null)\n        {\n            var url = userActivity.WebPageUrl.ToString();\n            DeepLinkService.Instance.HandleUrl(url);\n            return true;\n        }\n        return false;\n    }\n}\n<\/code><\/pre>\n\n\n\n
Android Configuration<\/h2>\n\n\n\n
1. Intent Filters<\/h3>\n\n\n\n
In Platforms\/Android\/AndroidManifest.xml<\/code>:<\/p>\n\n\n\n
<activity\n    android:name=".MainActivity"\n    android:exported="true">\n\n    <intent-filter android:autoVerify="true">\n        <action android:name="android.intent.action.VIEW" \/>\n        <category android:name="android.intent.category.DEFAULT" \/>\n        <category android:name="android.intent.category.BROWSABLE" \/>\n        <data android:scheme="https"\n              android:host="yourdomain.com"\n              android:pathPrefix="\/products" \/>\n        <data android:scheme="https"\n              android:host="yourdomain.com"\n              android:pathPrefix="\/offers" \/>\n        <data android:scheme="https"\n              android:host="yourdomain.com"\n              android:pathPrefix="\/referral" \/>\n    <\/intent-filter>\n<\/activity>\n<\/code><\/pre>\n\n\n\n
Or use the IntentFilter<\/code> attribute on MainActivity.cs<\/code>:<\/p>\n\n\n\n
using Android.App;\nusing Android.Content;\nusing Android.Content.PM;\n\n[Activity(\n    Theme = "@style\/Maui.SplashTheme",\n    MainLauncher = true,\n    Exported = true,\n    LaunchMode = LaunchMode.SingleTop)]\n[IntentFilter(\n    new[] { Intent.ActionView },\n    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },\n    DataScheme = "https",\n    DataHost = "yourdomain.com",\n    DataPathPrefix = "\/products",\n    AutoVerify = true)]\n[IntentFilter(\n    new[] { Intent.ActionView },\n    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },\n    DataScheme = "https",\n    DataHost = "yourdomain.com",\n    DataPathPrefix = "\/offers",\n    AutoVerify = true)]\n[IntentFilter(\n    new[] { Intent.ActionView },\n    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },\n    DataScheme = "https",\n    DataHost = "yourdomain.com",\n    DataPathPrefix = "\/referral",\n    AutoVerify = true)]\npublic class MainActivity : MauiAppCompatActivity\n{\n    protected override void OnCreate(Bundle savedInstanceState)\n    {\n        base.OnCreate(savedInstanceState);\n        HandleIntent(Intent);\n    }\n\n    protected override void OnNewIntent(Intent intent)\n    {\n        base.OnNewIntent(intent);\n        HandleIntent(intent);\n    }\n\n    private void HandleIntent(Intent intent)\n    {\n        if (intent?.Data != null)\n        {\n            DeepLinkService.Instance.HandleUrl(intent.Data.ToString());\n        }\n    }\n}\n<\/code><\/pre>\n\n\n\n
2. assetlinks.json<\/h3>\n\n\n\n
Host at https:\/\/yourdomain.com\/.well-known\/assetlinks.json<\/code>:<\/p>\n\n\n\n
[\n  {\n    "relation": ["delegate_permission\/common.handle_all_urls"],\n    "target": {\n      "namespace": "android_app",\n      "package_name": "com.yourcompany.yourapp",\n      "sha256_cert_fingerprints": [\n        "YOUR_SIGNING_KEY_FINGERPRINT"\n      ]\n    }\n  }\n]\n<\/code><\/pre>\n\n\n\n
Shared Deep Link Service<\/h2>\n\n\n\n
Create a service that both platforms call with the incoming URL:<\/p>\n\n\n\n
\/\/ Services\/DeepLinkService.cs\n\npublic class DeepLinkService\n{\n    private static DeepLinkService _instance;\n    public static DeepLinkService Instance => _instance ??= new DeepLinkService();\n\n    private string _pendingUrl;\n    private bool _isReady;\n\n    public void HandleUrl(string urlString)\n    {\n        if (_isReady)\n        {\n            RouteUrl(urlString);\n        }\n        else\n        {\n            \/\/ App not fully initialized yet, queue the URL\n            _pendingUrl = urlString;\n        }\n    }\n\n    public void MarkReady()\n    {\n        _isReady = true;\n        if (!string.IsNullOrEmpty(_pendingUrl))\n        {\n            RouteUrl(_pendingUrl);\n            _pendingUrl = null;\n        }\n    }\n\n    private void RouteUrl(string urlString)\n    {\n        if (!Uri.TryCreate(urlString, UriKind.Absolute, out var uri))\n            return;\n\n        var path = uri.AbsolutePath.TrimEnd('\/');\n        var query = System.Web.HttpUtility.ParseQueryString(uri.Query);\n\n        MainThread.BeginInvokeOnMainThread(async () =>\n        {\n            await NavigateFromDeepLink(path, query);\n        });\n    }\n\n    private async Task NavigateFromDeepLink(\n        string path,\n        System.Collections.Specialized.NameValueCollection query)\n    {\n        \/\/ Product page\n        var productMatch = System.Text.RegularExpressions.Regex.Match(\n            path, @"^\/products\/([^\/]+)$");\n        if (productMatch.Success)\n        {\n            var productId = productMatch.Groups[1].Value;\n            await Shell.Current.GoToAsync(\n                $"\/\/products\/detail?productId={productId}");\n            return;\n        }\n\n        \/\/ Offer page\n        var offerMatch = System.Text.RegularExpressions.Regex.Match(\n            path, @"^\/offers\/([^\/]+)$");\n        if (offerMatch.Success)\n        {\n            var offerId = offerMatch.Groups[1].Value;\n            await Shell.Current.GoToAsync(\n                $"\/\/offers\/detail?offerId={offerId}");\n            return;\n        }\n\n        \/\/ Referral\n        var referralMatch = System.Text.RegularExpressions.Regex.Match(\n            path, @"^\/referral\/([^\/]+)$");\n        if (referralMatch.Success)\n        {\n            var referrerId = referralMatch.Groups[1].Value;\n            \/\/ Store referral, then navigate to home\n            Preferences.Set("referrer_id", referrerId);\n            await Shell.Current.GoToAsync("\/\/home");\n            return;\n        }\n\n        \/\/ Default\n        await Shell.Current.GoToAsync("\/\/home");\n    }\n}\n<\/code><\/pre>\n\n\n\n
Shell Navigation Setup<\/h2>\n\n\n\n
Register routes in AppShell.xaml.cs<\/code>:<\/p>\n\n\n\n
public partial class AppShell : Shell\n{\n    public AppShell()\n    {\n        InitializeComponent();\n\n        \/\/ Register detail routes for deep linking\n        Routing.RegisterRoute("products\/detail", typeof(ProductDetailPage));\n        Routing.RegisterRoute("offers\/detail", typeof(OfferDetailPage));\n        Routing.RegisterRoute("referral", typeof(ReferralPage));\n    }\n}\n<\/code><\/pre>\n\n\n\n
AppShell.xaml<\/h3>\n\n\n\n
<?xml version="1.0" encoding="UTF-8" ?>\n<Shell xmlns="http:\/\/schemas.microsoft.com\/dotnet\/2021\/maui"\n       xmlns:x="http:\/\/schemas.microsoft.com\/winfx\/2009\/xaml"\n       xmlns:pages="clr-namespace:YourApp.Pages"\n       x:Class="YourApp.AppShell">\n\n    <TabBar>\n        <ShellContent Title="Home"\n                      Route="home"\n                      ContentTemplate="{DataTemplate pages:HomePage}" \/>\n        <ShellContent Title="Products"\n                      Route="products"\n                      ContentTemplate="{DataTemplate pages:ProductsPage}" \/>\n        <ShellContent Title="Offers"\n                      Route="offers"\n                      ContentTemplate="{DataTemplate pages:OffersPage}" \/>\n    <\/TabBar>\n<\/Shell>\n<\/code><\/pre>\n\n\n\n
Query Parameter Handling<\/h2>\n\n\n\n
Use QueryProperty<\/code> attributes to receive parameters on pages:<\/p>\n\n\n\n
[QueryProperty(nameof(ProductId), "productId")]\npublic partial class ProductDetailPage : ContentPage\n{\n    private string _productId;\n    public string ProductId\n    {\n        get => _productId;\n        set\n        {\n            _productId = value;\n            LoadProduct(value);\n        }\n    }\n\n    private async void LoadProduct(string productId)\n    {\n        if (string.IsNullOrEmpty(productId)) return;\n\n        try\n        {\n            var product = await ProductService.GetByIdAsync(productId);\n            BindingContext = product;\n        }\n        catch (Exception ex)\n        {\n            await DisplayAlert("Error", "Could not load product", "OK");\n            await Shell.Current.GoToAsync("..");\n        }\n    }\n}\n<\/code><\/pre>\n\n\n\n
App Initialization<\/h2>\n\n\n\n
Signal readiness after the app is fully initialized:<\/p>\n\n\n\n
\/\/ App.xaml.cs\npublic partial class App : Application\n{\n    public App()\n    {\n        InitializeComponent();\n        MainPage = new AppShell();\n    }\n\n    protected override void OnStart()\n    {\n        base.OnStart();\n        \/\/ Signal that the app is ready to handle deep links\n        DeepLinkService.Instance.MarkReady();\n    }\n}\n<\/code><\/pre>\n\n\n\n
Dependency Injection Alternative<\/h2>\n\n\n\n
Instead of the singleton pattern, use MAUI's built-in DI:<\/p>\n\n\n\n
\/\/ MauiProgram.cs\npublic static MauiApp CreateMauiApp()\n{\n    var builder = MauiApp.CreateBuilder();\n    builder\n        .UseMauiApp<App>()\n        .ConfigureFonts(fonts =>\n        {\n            fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");\n        });\n\n    \/\/ Register deep link service\n    builder.Services.AddSingleton<IDeepLinkService, DeepLinkService>();\n\n    return builder.Build();\n}\n<\/code><\/pre>\n\n\n\n
\/\/ Interface\npublic interface IDeepLinkService\n{\n    void HandleUrl(string url);\n    void MarkReady();\n}\n<\/code><\/pre>\n\n\n\n
Inject it where needed:<\/p>\n\n\n\n
public partial class App : Application\n{\n    private readonly IDeepLinkService _deepLinkService;\n\n    public App(IDeepLinkService deepLinkService)\n    {\n        InitializeComponent();\n        _deepLinkService = deepLinkService;\n        MainPage = new AppShell();\n    }\n\n    protected override void OnStart()\n    {\n        base.OnStart();\n        _deepLinkService.MarkReady();\n    }\n}\n<\/code><\/pre>\n\n\n\n
Testing<\/h2>\n\n\n\n
iOS Simulator<\/h3>\n\n\n\n
xcrun simctl openurl booted "https:\/\/yourdomain.com\/products\/abc123"\n<\/code><\/pre>\n\n\n\n
Android Emulator<\/h3>\n\n\n\n
adb shell am start -a android.intent.action.VIEW \\\n  -d "https:\/\/yourdomain.com\/products\/abc123" \\\n  -c android.intent.category.BROWSABLE\n<\/code><\/pre>\n\n\n\n
Unit Testing the Router<\/h3>\n\n\n\n
[TestFixture]\npublic class DeepLinkServiceTests\n{\n    [Test]\n    public void ParsesProductUrl()\n    {\n        var uri = new Uri("https:\/\/yourdomain.com\/products\/abc123");\n        var path = uri.AbsolutePath;\n\n        var match = Regex.Match(path, @"^\/products\/([^\/]+)$");\n\n        Assert.IsTrue(match.Success);\n        Assert.AreEqual("abc123", match.Groups[1].Value);\n    }\n\n    [Test]\n    public void ParsesQueryParameters()\n    {\n        var uri = new Uri("https:\/\/yourdomain.com\/products\/abc123?ref=email&campaign=summer");\n        var query = System.Web.HttpUtility.ParseQueryString(uri.Query);\n\n        Assert.AreEqual("email", query["ref"]);\n        Assert.AreEqual("summer", query["campaign"]);\n    }\n\n    [Test]\n    public void HandlesTrailingSlash()\n    {\n        var uri = new Uri("https:\/\/yourdomain.com\/products\/abc123\/");\n        var path = uri.AbsolutePath.TrimEnd('\/');\n\n        var match = Regex.Match(path, @"^\/products\/([^\/]+)$");\n\n        Assert.IsTrue(match.Success);\n        Assert.AreEqual("abc123", match.Groups[1].Value);\n    }\n}\n<\/code><\/pre>\n\n\n\n
Tolinku for .NET MAUI Apps<\/h2>\n\n\n\n
Tolinku<\/a> hosts AASA and assetlinks.json verification files. Configure your iOS Team ID, bundle identifier, Android package name, and SHA-256 fingerprints in the Appspace settings<\/a>, and Tolinku generates both files automatically. See the iOS configuration guide<\/a> and Android configuration guide<\/a> for setup details.<\/p>\n\n\n\n
For the legacy Xamarin approach, see Xamarin deep linking: cross-platform setup<\/a>. For building from scratch, see how to implement deep links from scratch<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
Add deep linking to .NET MAUI applications. Configure platform handlers, routing, and cross-platform link resolution in C# apps.<\/p>\n","protected":false},"author":2,"featured_media":1890,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":".NET MAUI Deep Linking: Implementation Guide","rank_math_description":"Add deep linking to .NET MAUI applications. Configure platform handlers, routing, and cross-platform link resolution in C# apps.","rank_math_focus_keyword":"MAUI deep linking","rank_math_canonical_url":"","rank_math_facebook_title":"","rank_math_facebook_description":"","rank_math_facebook_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-maui-deep-linking.png","rank_math_facebook_image_id":"","rank_math_twitter_title":"","rank_math_twitter_description":"","rank_math_twitter_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-maui-deep-linking.png","footnotes":""},"categories":[15],"tags":[25,23,156,567,20,566,24,69,22,565],"class_list":["post-1891","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-engineering","tag-android","tag-app-links","tag-cross-platform","tag-csharp","tag-deep-linking","tag-dotnet-maui","tag-ios","tag-mobile-development","tag-universal-links","tag-xamarin"],"_links":{"self":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/1891","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/comments?post=1891"}],"version-history":[{"count":1,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/1891\/revisions"}],"predecessor-version":[{"id":1892,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/1891\/revisions\/1892"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media\/1890"}],"wp:attachment":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media?parent=1891"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/categories?post=1891"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/tags?post=1891"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}