In the post, I will go thorough the core part of the tool, artifact and NuGet metadata, the way in which a NuGet package links to a native Android artifact.

Where they are

When checking out the tool, you will find there is a folder of android following the below structure.

|- path-to-the-tool
    |- src
        |- android
            |- android.arch.core
            |- android.arch.lifecycle

NOTE: The idea repo of the tool will be for both the iOS and Android binding libraries. Hence, there are two folders: one for android, one for ios.

In this android folder, each artifact group will have its own folder. Inside an artifact group folder, there will be

• group.json - Optional. Defines the info of the group such as name, dotnet8, etc.

• mavens.props - Optional. Defines custom Maven repositories.

• icon.png - Optional. The icon of the nested generated NuGet packages

• nested folders - Each folder is a nested artifact within the group.

Inside an artifact folder, we will have

• nuget.json - Required. Defines the info of the associated NuGet package

  • packageId - Required. It’s the package ID of associated NuGet package. If not present, it will be the Pascal version of artifact group and artifact names combined.

  • name - Optional. Normally it’s the name of the artifact. We can make it human friendly and SEO friendly.

  • dependencyOnly - Optional. Default to true. Marks that no binding should be generated.

  • versionMapping - Optional. This one is complex and complicated. It’s currently in use for Google related packages only.

• x.y.z.p.json files

  • The file name - The version of the native artifact

  • The file content:

    • revision: Optional. The revision of the Nuget package

    • fallbackVersion: Optional. The version which we should fallback to and this version actually has no associated NuGet package

• x.y.z.p.fixed.json files: Contains the fixed versions of the dependencies of the artifact when creating the binding library. We will learn more details about it in a concrete example.

For all of that long explanation, the main point is to define the way an Android artifact linked to a NuGet package.

How to update the existing metadata

These metadata is continuously updated by the NuGet packages’ owners. Hence, we will have to keep them up to date right before we want to do any new binding libraries or upgrade existing ones.

This update task is done by running this command in the BASH terminal

sh fetch.sh

This will check all existing metadata in our folder and check with NuGet.org to find any new versions added and/or modified with new revisions.

After the command is done, we must commit the change back to the tool for later reference.

How to add metadata for an Android binding NuGet package

Here are steps to add metadata for an Android binding NuGet package:

• Find the artifact group and artifact name of the native library

• Create folders for artifact group and artifact

• Create nuget.json file

  • packageId: The Nuget package id.

• Run sh fetch.sh

• Wait and see the result

• Commit the new metadata

Example of adding metadata for Xamarin.RevenueCat.Android which has the native library is com.revenuecat.purchases:purchases.

The result after running the fetch.

Wraps up

This is the basic info of the metadata, the core part of the tool. We will need to learn a bit further for special cases as we create binding libraries using the tool.

Happy binding!!!

• 1/ You normally embed the native libraries artifacts inside your DLL

  • 1.a/ This makes your DLL is potentially very large

  • 1.b/ It might causes conflicts if two different Nuget packages embed the same libraries

  • 1.c/ We cannot utilize if the native libraries are already downloaded by Android Studio or other Android development tools.

• 2/ You might try out Xamarin.Build.Download to download the libraries for you

  • The good point: We can get rid of item 1.a

  • Items 1.b & 1.c still persist

Other than that, a library normally doesn’t come without dependencies, we will have to analyze ourselves to find out

• if there is a NuGet available out there

• if not, we will need to create the binding ourselves

The things even get more headache when the libraries are privately distributed and protected with credentials on Gradle repositories.

By creating a lot of binding libraries (many are very big ones like Mapbox, Stripe, etc), I found the way that we can

• Utilize Gradle - the native tool to manage Android/Java libraries either without credentials or with credentials, to download the libraries for us and a.

• Find out the dependencies easily by reading POM files

• Find out which dependencies are already bound with public NuGet packages

• Upgrade version easily

In this series of Creating binding libraries for .NET Android, I will go through things step by step of how to use my approach for your own binding libraries based on my repository tuyen-vuduc/dotnet-binding-utils. At the end, you will get NuGet package(s) to use in your .NET Android app.

What do we have in this repository

1/ It is a toolset to create an .NET Android(Java) binding library

• It will analyze all dependencies of the targeting binding library by reading POM files downloaded by Gradle

• It will generate .NET Android (Java) binding library project(s) with appropriate dependencies

• It will build and pack the final result in NuGet packages

2/ It manages metadata of many .NET Android(Java) binding libraries

• Any Android (Java) binding libraries available on Nuget.org can have its metadata defined in this repo

• Based on available metadata, it will link the corresponding NuGet packages of the dependencies to the generated CSPROJ file

  • If a NuGet is available without its metadata,

    • 1/ We need to add a new one similar to existing ones

    • 2/ Then run the tool again

  • If not available, then a binding library project will be generated

3/ It has several scripts to simplify binding error fixes

// process_field(); // generate metadata to change fields’ managed names to avoid name conflicts.
// process_IJsonDeserializer(); // genereate xpath for classes inherits from IJsonDeserializer
// process_Com_Example_Dsroom_Dao_IBaseDao();
// process_Com_Google_Android_Material_Circularreveal_ICircularRevealWidget();
// process_Android_Util_ITypeEvaluator();
// process_Android_Util_Property();
// process_downgrade();

Here are typical steps to create a new binding library

1/ Fork my repository

2/ Open Git Bash on Windows or Terminal on other systems

3/ Ensure the existing metadata up to date by running sh fetch.sh

4/ Find the library Gradle details

• The Gradle implementation of the library e.g. de.hdodenhof:circleimageview:3.1.0

• The Gradle repository details

  • URL

  • Credentials

• By default, only these public repositories are supported

  • Maven Central

  • Google

  • JCenter

5/ Create the binding libraries by running sh bind.sh —artifact {YOUR_BINDIDNG_LIBRARY_IMPLEMETNATION_SYNTAX_IN_GRADLE}

6/ Fix all binding errors as reported then do the step 5 again until no more errors reported

7/ Create a PR to merge your changes to the main repository

If you’re lucky, you won’t have to do step 6 where no errors reported, there will be NuGet packages generated in nugets folder. Otherwise, you need to be patient and careful to fix all reported errors then do step 7 as the final step.

With generated NuGet packages, you can consume them locally or distribute wherever you prefer.

Let’s create a binding library

In this simple demonstration, let’s create the binding library for de.hdodenhof:circleimageview:3.1.0 as mentioned the guide from Microsoft referred early in this post.

1/ Fork the library

Please do the fork then clone to your local machine if you haven’t.

2/ Open bash based terminal

• Open the repository in Visual Studio Code

• Open bash based terminal panel as well

  • On Windows, I normally use Git Bash which is installed along with Git for Windows.

3/ Ensure the metadata up-to-date

I created a simple XUnit test to fetch the metadata of the existing libraries defined in the repository easily.

To invoke the update process, simply run sh fetch.sh on your preferred bash based terminal.

On Windows, I recommend use Git Bash which comes along when you install Git for Windows.

As you can see, after running the script, there are many libraries updated either a new patch or even a new version.

Commit these changes before moving onward.

4/ Find the library’s Gradle details

After searching circleimageview on Google Search, we can see its GitHub repository

By checking out the README, we can easily find out the Gradle implementation of the library.

dependencies {
    ...
    implementation 'de.hdodenhof:circleimageview:3.1.0'
}

What we need is the value of de.hdodenhof:circleimageview:3.1.0

NOTE: Android/Libraries are normally distributed on Maven Central repository which is similar to NuGet.org in .NET world. You can search for the libraries there as well to easily get their latest versions if not presented in the README.

5/ Create the binding library

Creating a binding library normally requires many steps, but I created a script, bind.sh, to make our life easier. Executing it will

• Create the binding library project for the targeted library

• Add NuGet packages for all dependencies having corresponding metadata

• Add and link binding projects for dependencies without corresponding metadata

The syntax is

# sh bind.sh —artifact {ARTIFACT_GROUP}:{ARTIFACT_NAME}:{VERSION}
sh bind.sh —artifact de.hdodenhof:circleimageview:3.1.0

Here is what you can see when executing sh bind.sh —artifact de.hdodenhof:circleimageview:3.1.0

• It’s starting

• It’s successfully without any binding errors

As you can see on the right left hand side, a binding project is created with all required files which are for fixing binding errors.

6/ Fix reported binding errors

As you can see, no errors are reported, then we can skip this step.

The process of fixing binding errors sometimes is very simple, but sometimes is very complex; however, we need to always follow the guide from Microsoft as the base line.

7/ Create the PR to merge your new binding library to my repository

Commit all the changes then create the PR.

Please follow the guide from GitHub to complete this step.

We can skip if for now and check out the generated library packed as a NuGet library first.

You can use it locally or upload it to NuGet.org then use. If you prefer a local try first, you can check out this guide if you don’t know yet.

Wraps up

In this post, I introduced you my repository dotnet-binding-utils which is to utilize Gradle and other custom scripts to simplify the process of creating an Android binding library. The major benefits are

• Utilize the native Android package management to manage Android dependencies

• Reduce diskspace if we work on both Android native development and .NET Android development

• Simple process

• Results consumed easily as NuGet packages

I hope it will help and benefit you guys.

It’s just the start, there are many other scenarios, please check out my other related posts (upcoming).

Happy coding!!!

NOTE: Microsoft also introduced a new way of adding a native Android library which is publicly available on Maven Central library. What I don’t like is it doesn’t utilize Gradle but Xamarin.Build.Download to download the dependency.

Stripe is a very well known payment service to let your end users pay easily and beautifully for your product/service(s) within your mobile apps and websites.

This article will guide you steps to integrate Stripe SDK into a newly created .NET MAUI app step by step.

Prerequisites

• .NET 8

• Java SDK 17

• Visual Studio on Windows or Visual Studio for Mac, alternatively

  • JetBrains Rider alternatively

  • Visual Studio Code with .NET MAUI extension

• .NET workloads for .NET MAUI

• Download the get-started source code

Steps

0/ Open the downloaded solution dotnet-maui-stripe-get-started.sln

0.a/ Create Shared.dev.cs file by making a copy of Shared.dev.cs.sample

|--src
    |-- QuickStart.Dotnet.StripeHost
        |-- Shared.cs
        |-- Shared.dev.cs        <------      YOUR_FILE_HERE

0.b/ Replace placeholders with your secrets

partial class ClientHelper
{
    public const string API_KEY = "YOUR_API_KEY";
    public const string DEFAULT_PUBLISHABLE_KEY = "YOUR_DEFAULT_PUBLISHABLE_KEY";
}

HINTS: You can copy these secrets quickly from the official quick start by Stripe.

0.c/ Run the API host

cd your-path-to-source-code/src/QuickStart.Dotnet.StripeHost
dotnet run -c debug

0.d/ Expose your API endpoint with ngrok

ngrok http http://localhost:4242

NOTE: ngrok is a tool that allows us to expose a development endpoint publicly via the network with ease.

0.e/ Amend Shared.dev.cs with the generated URL

partial class ClientHelper
{
    public const string BACKEND_URL= "https://generated-subdomain.ngrok-free.app";
}

1/ Create a new .NET MAUI app from Visual Studio

NOTE: Follow step by step with all default options

2/ Install Stripe SDK for .NET MAUI

2.a/ Upgrade all .NET MAUI packages before installing Stripe.MAUI package

2.b/ Search for Stripe.Maui package and install

NOTE:

• Before going next

  • Close the solution

  • Remove bin/obj folders of the .NET MAUI project

  • Reopen the solution

• IMPORTANT!!! If you faced any issues of project loading failed, please repeat these steps :D

3/ Enable Stripe in MauiProgram.cs

3.a/ Add shared files to the .NET MAUI project

NOTE: We will add these files as links to share code across projects.

3.b/ Add Stripe to MauiAppBuilder

builder
    .UseStripe(
        QuickStart.Dotnet.Stripe.ClientHelper.DEFAULT_PUBLISHABLE_KEY
    );

4/ Inject IPaymentSheet into MainPage.xaml.cs

public partial class MainPage : ContentPage
{
    private readonly IPaymentSheet paymentSheet;

    public MainPage(IPaymentSheet paymentSheet)
    {
        InitializeComponent();
        this.paymentSheet = paymentSheet;
    }
}

NOTE: To get the DI to work, we need to register MainPage as a scoped dependency through MauiAppBuilder.

// In MauiProgram.cs
builder.Services.AddScoped<MainPage>();

5/ Try paying with payment intent

5.a/ Override MainPage.xaml file with the below content

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="GetStartedWithStripe.MainPage">
    <StackLayout
        Padding="30,24"
        Spacing="25">
        <Button
            x:Name="PayNowButton"
            Text="Pay now"
            SemanticProperties.Hint="Pay with Stripe"
            Clicked="OnPayNow"
            IsEnabled="False"
            VerticalOptions="EndAndExpand"
            HorizontalOptions="Fill" />
    </StackLayout>
</ContentPage>

5.b/ Fetch payment intent client secret from the above API endpoint

private string paymentIntentClientSecret;
protected override async void OnAppearing()
{
    base.OnAppearing();

    // The helper method comes from the downloaded source code
    await QuickStart.Dotnet.Stripe.ClientHelper.FetchPaymentIntent()
        .ContinueWith(t =>
        {
            var (ok, msg) = t.Result;
            if (!ok)
            {
                MainThread.BeginInvokeOnMainThread(() => DisplayAlert("API Error", msg, "OK"));
                return;
            }

            paymentIntentClientSecret = msg;

            MainThread.BeginInvokeOnMainThread(() => PayNowButton.IsEnabled = true);
        })
        .ConfigureAwait(false);
}

NOTE:

• By default, Pay now button is disabled

• It will only be enabled if we can fetch the client secret successfully from the API

5.c/ Add OnPayNow handler

    private async void OnPayNow(object sender, EventArgs e)
    {
        var configuration = new Configuration("TuyenTV.dev Co.Ltd.");

        var (result, msg) = await paymentSheet.PresentWithPaymentIntentAsync(paymentIntentClientSecret, configuration)
            .ContinueWith(t =>
            {
                if (t.IsCompletedSuccessfully) return (t.Result, null);

                return (PaymentSheetResult.Canceled, "Cannot pay for a reason...");
            });

        switch(result)
        {
            case PaymentSheetResult.Completed:
                await DisplayAlert("Payment Result", "Payment completed successfully!", "OK");
                break;
            case PaymentSheetResult.Canceled:
                if (!string.IsNullOrWhiteSpace(msg))
                {
                    await DisplayAlert("Payment Result", "Payment completed failed!", "Try again");
                }
                break;
        }

        Debug.WriteLine("Payment complete.");
    }

6/ Run up and check out

Till now, you're ready to check out the result on both Android and iOS.

• Android: You can try either on a emulator or on a real device by plugging it in directly to your PC

• iOS:

  • If you have an Apple paid developer account, you can plug your iPhone directly to your PC and try out

  • Otherwise, you will need a MacOS device to run the simulator

Wrap-ups

I just guided you on how to integrate Stripe SDK into a newly created .NET MAUI project. You can follow these steps to add it to your project(s) easily.

Documents from Stripe are also very helpful, please always take a look to understand a feature you desire to add to your app.

If you want to check out the source code of the binding libraries, you can check it here. If you want to check out the source code of the .NET MAUI library (along with a sample app), you can check it here.

Happy Coding!!!

As an mobile app developer, you might ever think if your users can be your app testers who can log an encountered bug with a lot of details for our triage and bug fixing like screenshot, app logs, etc. Sometime, your users also want to give an idea of improvement, but they can't help.

Understanding this paint point, there are many services out there to help us. ShakeBugs is one of them, an SaaS service for collecting and managing bugs and improvements from our app users in production.

This article will guide you how to integrate ShakeBugs SDK into your .NET MAUI application step by step.

Prerequisites

• .NET 8

• Java SDK 17

• Visual Studio on Windows or Visual Studio for Mac, alternatively

  • JetBrains Rider alternatively

  • Visual Studio Code with .NET MAUI extension

• .NET workloads for .NET MAUI

Steps

1/ Create ShakeBugs apps for iOS and Android

Creating ShakeBugs apps is pretty easy, you can simply follow the steps as you go after logging in in their portal.

We need to create two apps

• One for Native Android

• One for Native iOS

2/ Create a new .NET MAUI project

NOTE: Please update all .NET MAUI packages to the latest version (8.0.60 at the time of this writing).

NOTE: As we only target Android and iOS platforms, so we should remove other platforms from our CSPROJ file.

3/ Install ShakeBugs for .NET MAUI NuGet package

You can search for ShakeBugs.Maui from the NuGet package manager window.

Or you can simply open the CSPROJ file then add these lines

<PackageReference Include="ShakeBugs.MAUI">
  <Version>17.0.0</Version>
</PackageReference>

4/ Amend MauiProgram.cs to have ShakeBugs enabled

builder
    ...
    .UseShakeBugs(
        androidApiKey: "YOUR_ANDROID_API_KEY",
        iosApiKey: "YOUR_IOS_API_KEY",
        crashReportingEnabled: true
    )
    ...

5/ Voila! Run the app up and shake your device

After you get above steps done, you are now ready to check out ShakeDebugs user interface with two steps

• 1/ Run up the app

• 2/ Shake your device

Wrap ups

I just guided you on how to integrate ShakeBugs SDK into a .NET MAUI project. You can follow the steps and add it to your project(s) easily.

Documents from ShakeBugs are also very helpful, please take a look to understand all features it provides.

If you want to check out the source code of the binding libraries, you can check it here. If you want to check out the source code of the .NET MAUI library (along with a sample app), you can check it here.

Happy coding!!!

Mapbox is a well-known service for maps and location and it provides its SDKs for multiple platforms from the web to the mobile. Within the mobile, there are prebuilt SDKs for ReactNative and Flutter, but none for Xamarin.Forms/.NET MAUI.

Recently, I successfully created and published the NuGet package for integrating Mapbox SDKs to a Xamarin.Forms and/or .NET MAUI app.

dotnet add package Mapbox.Maui --version 11.4.0-alpha01

In this blog, I will guide you through the steps to use that mentioned NuGet package in a .NET MAUI app.

TLTR; You can access the full quickstart example from this GitHub repo.

Prerequisites

• Visual Studio for Mac or Visual Studio on Windows (VS Code)

• .NET 8.0.100

• .NET workloads for Android, iOS, MAUI

Steps

Assumption: We will start with a totally new, empty .NET MAUI app.

1/ Config your MAPBOX_DOWNLOADS_TOKEN

At the moment, this setup for iOS and Android is a little bit different, so we have to do it twice, differently for each platform. You can read my blog posts for .NET Android and for .NET iOS for further details.

• Grab your MAPBOX_DOWNLOADS_TOKEN from your Mapbox account page

• Put that token ~/.gradle/gradle.properties from the terminal (Replace YOUR_MAPBOX_DOWNLOADS_TOKEN with yours)

echo "MAPBOX_DOWNLOADS_TOKEN=YOUR_MAPBOX_DOWNLOADS_TOKEN" >> ~/.gradle/gradle.properties

• Amend your .csproj file with the following lines (Replace YOUR_MAPBOX_DOWNLOADS_TOKEN with yours)

<PropertyGroup>
    <MAPBOX_DOWNLOADS_TOKEN>YOUR_MAPBOX_DOWNLOADS_TOKEN</MAPBOX_DOWNLOADS_TOKEN>
</PropertyGroup>
<ItemGroup>
    <GradleRepository Include="https://api.mapbox.com/downloads/v2/releases/maven">
      <Repository>
      maven {
         url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
         authentication {
             create&lt;BasicAuthentication&gt;("basic")
         }
         credentials {
             // Do not change the username below.
             // This should always be `mapbox` (not your username).
             username = "mapbox"
             // Use the secret token you stored in gradle.properties as the password
             password = providers.gradleProperty("MAPBOX_DOWNLOADS_TOKEN").get()
         }
      }
      </Repository>
    </GradleRepository>
</ItemGroup>

NOTE:MAPBOX_DOWNLOADS_TOKENis a sensitive data item, it shouldn't be committed to our git repository. We should put it in an ignored file, but still understandable by the compiler.

2/ Add Mapbox MAUI for .NET to your project

• Open NuGet Package Manager

  

• Search for the package Mapbox.Maui

• Add it to your project

  

• Check the result

  

• Try to build the project

  A successful build means you did it well by far

4/ Configure mapbox_access_token

To work with Mapbox APIs, we have to generate a personalized access token from our Mapbox account page and then put it into our project to use

• Generate/grab the access token

  

  You can use the default public token for this tutorial. If you want more control over what scopes to be used, please create a new token

• Amend MauiProgram.cs as the below code snippet

    public static class MauiProgram
    {
        // Please put your MAPBOX_ACCESS_TOKEN here
        const string ACCESS_TOKEN = "YOUR_MAPBOX_ACCESS_TOKEN";
  
        public static MauiApp CreateMauiApp()
        {
            // ...
            builder
                // ...
                .UseMapbox(ACCESS_TOKEN);
            // ...
  

  NOTE: mapbox_access_token is a sensitive data item, it shouldn't be committed to our git repository. We should put it in an ignored file, but still understandable by the compiler.

5/ Add MapView control to your app

• In XAML MainPage.xaml

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage
    ...
    xmlns:mb="clr-namespace:MapboxMaui;assembly=Mapbox.Maui"
    ...>

    <mb:MapboxView />
</ContentPage>

• Remove all old logic in MainPage.xaml.cs

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
    }
}

• Check out the result

NOTE: You can also initialize MapView instance directly from C#.

Wrap up

I just guided you on how to use Mapbox in a .NET MAUI project.

I already ported 10 out of 66 iOS examples to .NET MAUI. You can check out Mapbox SDK for .NET MAUI repository.

I want to port all the rest to .NET MAUI, but it'll be a time-consuming task. Single me will last for a very long time. I hope the community can contribute to this GitHub repo and/or to their repos.

Mapbox is a well-known service for maps and location and it provides its SDKs for multiple platforms from the web to the mobile. Within the mobile, there are SDKs for Android, iOS, ReactNative and Flutter, but none for Xamarin/.NET iOS.

Recently, I successfully created and published the NuGet package for integrating Mapbox iOS SDK to your Xamarin.iOS and/or .NET iOS app.

dotnet add package MapboxMapsObjC.iOS --version 11.4.0

In this blog, I will guide you through the steps to use that mentioned NuGet package in a .NET iOS app.

TLTR; You can access the full quickstart example from this GitHub repo.

Prerequisites

• Visual Studio for Mac or Visual Studio on Windows

• .NET 8.0.100

• .NET for iOS workload

Steps

Assumption: You already have a .NET iOS app. If not, you can just create a new empty .NET iOS app to follow this guide.

1/ Config your MAPBOX_DOWNLOADS_TOKEN

Mapbox iOS SDK is distributed privately via Mapbox's CDN which we can configure SPM/CocoaPods to download or download directly the artifacts with a MAPBOX_DOWNLOADS_TOKEN. To know how to generate that token, please check out the official guide from Mapbox.

Xamarin.iOS/.NET iOS doesn't work with SMP/Cocoapods, but we can leverage Xamarin.Build.Download package to help us download the artifacts using Direct Download approach when building the app by following these steps:

• Generate/grab MAPBOX_DOWNLOADS_TOKEN from your Mapbox account page

  

• Amend your .csproj file with the following lines

<PropertyGroup>
    <MAPBOX_DOWNLOADS_TOKEN>YOUR_MAPBOX_DOWNLOADS_TOKEN</MAPBOX_DOWNLOADS_TOKEN>
</PropertyGroup>

NOTE:MAPBOX_DOWNLOADS_TOKENis a sensitive data item, it shouldn't be committed to our git repository. We should put it in an ignored file, but still understandable by the compiler.

2/ AddMapbox iOS SDK for .NET to your project

• Open NuGet Package Manager

  

• Search for the package MapboxMapsObjC.iOS

  

• Add it to your project

  

• Try to build the project

  A successful build means you did it well by far

3/ Configure mapbox_access_token

To work with Mapbox APIs, we have to generate a personalized access token from our Mapbox account page and then put it into our project to use

• Generate/grab the access token

  

  You can use the default public token for this tutorial. If you want more control over what scopes to be used, please create a new token

• Put the generated access token into Info.plist

    <key>MBXAccessToken</key>
    <string>YOUR_MAPBOX_ACCESS_TOKEN</string>
  

  NOTE:mapbox_access_token is a sensitive data item, it shouldn't be committed to our git repository. We should put it in an ignored file, but still understandable by the compiler.

4/ Add MapView control to your app

• Create MapboxViewController

public class MapboxViewController : UIViewController
{
}

• Add MapView instance with default options in ViewDidLoad

public override void ViewDidLoad()
{
    base.ViewDidLoad();

    // Use all default options
    var options = MapInitOptionsFactory.CreateWithResourceOptions(
        null, null, null, null, null
        );

    var mapView = MapViewFactory.CreateWithFrame(View.Bounds, options);
    mapView.AutoresizingMask = UIViewAutoresizing.FlexibleWidth | UIViewAutoresizing.FlexibleHeight;

    View.AddSubview(mapView);
}

• Change RootViewController in AppDelegate.cs file

public override bool FinishedLaunching (UIApplication application, NSDictionary launchOptions)
{
    // create a new window instance based on the screen size
    Window = new UIWindow (UIScreen.MainScreen.Bounds);

    Window.RootViewController = new MapboxViewController();

    // make the window visible
    Window.MakeKeyAndVisible ();

    return true;
}

• Check the result

  

Wrap up

I just guided you on how to use Mapbox in a .NET iOS project. You can do the same steps for a Xamarin.iOS project.

I want to port all native examples to .NET iOS, but it'll be a time-consuming task. Single me will last for a very long time. I hope the community can contribute to this GitHub repo and/or to their repos.

Mapbox is a well-known service for maps and location and it provides its SDKs for multiple platforms from the web to the mobile. Within the mobile, there are SDKs for Android, iOS, ReactNative and Flutter, but none for Xamarin/.NET Android.

Recently, I successfully created and published the NuGet package for integrating Mapbox Android SDKs to your Xamarin.Android and/or .NET Android app.

dotnet add package Com.Mapbox.Maps.Android --version 11.4.1

In this blog, I will guide you through the steps to use that mentioned NuGet package in a .NET Android app.

TLTR; You can access the full quickstart example from this GitHub repo.

Prerequisites

• Visual Studio for Mac or Visual Studio on Windows

• .NET 8.0.100

• .NET for Android workload

Steps

Assumption: You already have a .NET Android app. If not, you can just create a new empty .NET Android app to follow this guide.

1/ Config your MAPBOX_DOWNLOADS_TOKEN

Mapbox Android SDK is distributed privately via Mapbox's dedicated Maven repository which requires a personalized MAPBOX_DOWNLOADS_TOKEN to get the Gradle build to download the required artifacts.

FYI: Mapbox Android SDK for .NET makes use of Gradle to download its native dependencies.

• Grab your MAPBOX_DOWNLOADS_TOKEN from your Mapbox account page

• Put that token ~/.gradle/gradle.properties from the terminal

echo "MAPBOX_DOWNLOADS_TOKEN=YOUR_MAPBOX_DOWNLOADS_TOKEN" >> ~/.gradle/gradle.properties

You can follow the official guide from Mapbox to complete this step.

2/ Add Mapbox Android SDK for .NET to your project

• Open NuGet Package Manager

  

• Search for the package Com.Mapbox.Maps.Android

  

• Add it to your project

  

NOTE: If you failed to add the nuget package, please check Package Console output window and resolve all mismatching dependencies. (I expect VS can do it for us, but it cannot)

• Add these other required packages as well to resolve incompatibility issues

<PackageReference Include="Xamarin.AndroidX.AppCompat" Version="1.6.1.10" />
<PackageReference Include="Xamarin.AndroidX.Fragment " Version="1.7.0.2" />
<PackageReference Include="Xamarin.AndroidX.Fragment.Ktx" Version="1.7.0.2" />

• Check the result

3/ Add Mapbox maven repository to .csproj

As I mentioned earlier, we will leverage Gradle, an Android build system, to resolve and download all Mapbox SDK's artifacts for us. To make that happen, we will need to amend our Android .csproj file.

• Open .csproj file in VS or VSCode

• Add these lines

•   <ItemGroup>
      <GradleRepository Include="https://api.mapbox.com/downloads/v2/releases/maven">
        <Repository>
          maven {
            url = uri("https://api.mapbox.com/downloads/v2/releases/maven")
            authentication {
              create&lt;BasicAuthentication&gt;("basic")
            }
            credentials {
              // Do not change the username below.
              // This should always be `mapbox` (not your username).
              username = "mapbox"
              // Use the secret token you stored in gradle.properties as the password
              password = providers.gradleProperty("MAPBOX_DOWNLOADS_TOKEN").get()
            }
          }
        </Repository>
      </GradleRepository>
    </ItemGroup>
  

• Try to build the project

  A successful build means you did it well by far

4/ Configure mapbox_access_token

To work with Mapbox APIs, we have to generate a personalized access token from our Mapbox account page and then put it into our project to use

• Generate/grab the access token

  

  You can use the default public token for this tutorial. If you want more control over what scopes to be used, please create a new token

• Copy the generated access token to Resources/values/strings.xml

    <resources>
       <string name="mapbox_access_token">YOUR_MAPBOX_ACCESS_TOKEN</string>
    </resources>
  

  NOTE: mapbox_access_token is a sensitive data item, it shouldn't be committed to our git repository. We should put it in an ignored file, but still understandable by the compiler.

  

5/ Add MapView control to your app

• In XML Resources/layout/activity_main.xml

<com.mapbox.maps.MapView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/mapView"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

• Ensure your activity inherits from AppCompatActivity and use an AppCompat theme

[Activity(
    Label = "@string/app_name",
    MainLauncher = true,
    Theme = "@style/Theme.AppCompat.Light.DarkActionBar")]
public class MainActivity : AppCompatActivity
{
    // ...
}

• Access mapView instance from C#

[Activity(
    Label = "@string/app_name",
    MainLauncher = true,
    Theme = "@style/Theme.AppCompat.Light.DarkActionBar")]
public class MainActivity : AppCompatActivity
{
    MapView mapView;
    protected override void OnCreate(Bundle? savedInstanceState)
    {
        base.OnCreate(savedInstanceState);
        SetContentView(Resource.Layout.activity_main);
        mapView = FindViewById<MapView>(Resource.Id.mapView);
    }
}

• Override life-cycle methods

    // ...
    protected override void OnStart()
    {
        base.OnStart();
        mapView?.OnStart();
    }

    protected override void OnStop()
    {
        base.OnStop();
        mapView?.OnStop();
    }

    public override void OnLowMemory()
    {
        base.OnLowMemory();
        mapView?.OnLowMemory();
    }

    protected override void OnDestroy()
    {
        base.OnDestroy();
        mapView?.OnDestroy();
    }
    // ...

• Check out the result

NOTE: You can also initialize MapView instance directly from C# exactly in the same way you find in Mapbox native examples.

Wrap up

I just guided you on how to use Mapbox in a .NET Android project. You can do the same steps for a Xamarin.Android project.

I want to port all native examples to .NET Android, but it'll be a time-consuming task. Single me will last for a very long time. I hope the community can contribute to this GitHub repo and/or to their repos.

.NET MAUI is the successor to Xamarin.Forms which ends the mission in 2024. .NET MAUI was expected to be GM in 2021 but was finally out of beta in the first half of 2022. .NET MAUI is a promise from Microsoft in the competence with Flutter, a trending toolkit from Google, to overcome all the disadvantages of Xamarin.Forms.

Technically, .NET MAUI is rewritten from scratch to avoid all technical debts in Xamarin.Forms and leverage all the goodness from .NET6 and the latter. However, how the UI is rendered on each platform is almost the same as Xamarin.Forms as demonstrated below.

Why an app template?

As mentioned above, .NET MAUI is quite new, so there aren't so many apps built out there for reference yet, neither publically nor personally. Building an app using Xamarin.Forms for years, I believe all the best practices I applied for Xamarin.Forms will benefit MAUI apps and I created Chick and Paddy MAUI app template.

What the template provides

1) A clean, feature-based architecture

I am a fan of clean and feature-based (module-based) architecture, I tried to apply it where I can regardless of the technologies I used. Here is the screenshot of the high-level architecture of the template.

In this template, the external dependencies are all just a few

• Community Toolkit - MVVM

• Community Toolkit - MAUI

It'll be thin and light to make the best out of the default. We might not need other fancy libraries and/or frameworks to help.

2) Common MVVM classes

Base classes will reassure the consistency of the overall architecture. In this template, such classes inherit from MVVM Community Toolkit base classes (ObservableObject, ObservableValidator) to leverage all the common best practices and code generators from Microsoft.

• BaseModel -- The base class for data model classes.

• BaseFormModel -- The base class for form model classes that require validations on their properties.

• BaseViewModel -- The base class for all ViewModel classes.

• NavigationAwareBaseViewModel - The base class for ViewModel classes which needs to handle navigation events and data.

3) Hiding MAUI from ViewModel with AppNavigator

Starting from Xamarin.Forms, Shell was introduced to simplify the navigation with .NET mobile apps. However, it'll be a bad practice, in MHO, if we use that class directly in our ViewModel to do navigation. I introduced IAppNavigator as the contract for all navigation operations and AppNavigator to hide Shell methods from ViewModels.

public Task NavigateAsync(string target, bool animated = false, object args = default)
    {
        // ... preconfigure
        return MainThread.InvokeOnMainThreadAsync(() => Shell.Current.GoToAsync(
            target,
            animated,
            navArgs
        );
    }

With IAppNavigator, we can do UnitTesting of our ViewModels without the knowledge of Shell at all.

4) Descriptive readme & code generation script

I wrote a very descriptive readme to help the other developers to get started with the template in a few minutes.

The readme is written with a lot of code snippets, outlined details and diagrams to understand better the design idea.

The code generation script will simplify the way we create a new page that strictly follows my pattern.

5) Easter eggs

• EdgeInsetExtension -- a markup extension to simplify the way we handle Thickness properties like Padding, Margin - it was inspired by Flutter way.

• Many others: reusable converters, markup extensions, and naming conventions.

Final thoughts

.NET MAUI still requires a lot of effort to get to the speed of its competitors, but it's ready to use for your new mobile apps if you want to use .NET or migrate your Xamarin.Forms apps. I already built apps for my clients using MAUI and this template.

I hope this template will benefit you guys as well.

Happy coding!

In 2017, I found up Naxam with the aim to build a great software development company specialized in Microsoft technologies, started with Xamarin. Following my way of learning, I chosen a pet project for the first Nxers to learn and practice their Xamarin skills. I chose Busuu, a world leading application for learning English skills, because it has a beautiful UI/UX and I strongly believe my Nxers can improve both technical skills and English skills through out the project.

Nxers ~ Naxam's people

What we gained

• A bulk of features cloned are runnable with mock data
• All people joined can do Xamarin project at various levels of confidence
• All people understood how to form up a good architecture for a Xamarin.Native app
• The company had its first Xamarin capable team to handle incoming projects

Why I made it open sourced

This pet project was made private and only available for internal Nxers to refer to while building a Xamarin.Native application. However, Naxam is no longer in business for years now, I think this pet project will benefit other developers around the world when finding a good MvvmCross sample application specifically and a .NET application in general.

This project is also to show the way I normally organize a .NET application where I am the tech lead of the project.

Please find out the repo on Github. Please star if it benefits you.

Credits

I would like to say "Thank you" to all of my Nxers who had been working with me for that so long. This project was made by them and always belongs to them. You can find their github in the README of the project.

NOTE: This project was made in the early of 2017, so the referenced libraries are outdated by now.