Document how to work with a local ASP.NET Core backend during development

[danroth27]

Port the following Xamarin docs on consuming backend APIs from a native client app during development:

• https://docs.microsoft.com/xamarin/xamarin-forms/data-cloud/web-services/rest
• https://docs.microsoft.com/xamarin/cross-platform/deploy-test/connect-to-local-web-services

We'll also need to migrate the Todo sample app to .NET MAUI as well.

This is needed so that we can update the ASP.NET Core tutorial on building an ASP.NET Core backend for a native client: dotnet/AspNetCore.Docs#26109.

[davidbritch]

• Sample
  • API
  • MAUI client
  • Use Shell navigation
  • Use DI
  • Replace ListView with CollectionView
  • Tidy up UI
  • Works on all platforms
    • Windows
      • Localhost HTTP
      • Localhost HTTPS
      • Hosted HTTPS
    • Android
      • Localhost HTTP - MAUI: add network_security_config, API: add a HTTP profile
      • Localhost HTTPS - override AndroidMessageHandler and ignore localhost SSL errors via ServerCertificateCustomValidationCallback
      • Hosted HTTPS
    • iOS
      • Localhost HTTP - enable ATS (allow local networking).
      • Localhost HTTPS - set NSUrlSessionHandler.TrustOverrideForUrl to a delegate that trusts HTTPS localhost
      • Hosted HTTPS
    • MacCatalyst
      • Localhost HTTP
      • Localhost HTTPS
      • Hosted HTTPS
• Consume REST services doc
• Connect to local web services doc

[davidbritch]

In typical fashion this won't be a straight port. The old way of connecting to localhost from Android doesn't work in MAUI - see dotnet/android#6665

[danroth27]

@davidbritch dotnet/android#6665 is a merged PR. Is there an active issue tracking the problem you are seeing?

[davidbritch]

@danroth27 It's more a question of what modifications are required to the Android config in the MAUI app to make it connect to both HTTP and HTTPS localhost without errors. I'm working on it.

[AndreduToit]

I am also experiencing problems with connecting to localhost from Android in MAUI and searching for a solution to this issue. Would appreciate any update/solution that you may have.

[davidbritch]

Hi @AndreduToit

There'll be docs on doing this by the end of the week. In the meantime, let's see if I can help you. Are you trying to connecting to HTTP localhost or HTTPS? The solution is different for each scheme.

[AndreduToit]

Hello @davidbritch
Thank you so much for your response.
I let you know that I have also engaged with @Eagle3386 on this issue see: dotnet/maui#8131.

I am trying to connect to HTTPS with my .NET Maui App.
The App works as expected on Windows platform but on Android platform the server responds with 'Hostname 10.0.2.2 not verified'

I have added the following to my Maui App:

• Platforms\Android\Resources\raw\kestrel.cer
• Platforms\Android\Resources\xml\network_security_config.xm - as per the suggestion by @Eagle3386.
• line - android:networkSecurityConfig ="@xml/network_security_config" - under tags 'manifest/application' in AndroidManifest.xml

I re-produced kestrel.cer in dotnet with command line 'dotnet dev-certs https --clean' and 'dotnet dev-certs https --trust' and exported the certificates with certmgr.exe to the folder Android\Resources\raw in my Maui App (tried both DER encoded and Base-64 encoded formats in 'Personal' and 'Trusted Root Certificate Authorities' folders).

I would very much appreciate any tips or guidance that you can give me.

[davidbritch]

Hi @AndreduToit

The network_security_config.xml approach is for HTTP. The issue on HTTPS is that Android doesn't trust self-signed certificates, and so you have to add code to ignore SSL errors for localhost. Add the following class to your project:

    public class HttpsClientHandlerService : IHttpsClientHandlerService
    {
        public HttpMessageHandler GetPlatformMessageHandler()
        {
#if ANDROID
            var handler = new CustomAndroidMessageHandler();
            handler.ServerCertificateCustomValidationCallback = (message, cert, chain, errors) =>
            {
                if (cert != null && cert.Issuer.Equals("CN=localhost"))
                    return true;
                return errors == System.Net.Security.SslPolicyErrors.None;
            };
            return handler;
#elif IOS
            var handler = new NSUrlSessionHandler
            {
                TrustOverrideForUrl = IsHttpsLocalhost
            };
            return handler;
#elif WINDOWS || MACCATALYST
            return null;
#else
         throw new PlatformNotSupportedException("Only Android, iOS, MacCatalyst, and Windows supported.");
#endif
        }

#if ANDROID
        internal sealed class CustomAndroidMessageHandler : Xamarin.Android.Net.AndroidMessageHandler
        {
            protected override Javax.Net.Ssl.IHostnameVerifier GetSSLHostnameVerifier(Javax.Net.Ssl.HttpsURLConnection connection)
                => new CustomHostnameVerifier();

            private sealed class CustomHostnameVerifier : Java.Lang.Object, Javax.Net.Ssl.IHostnameVerifier
            {
                public bool Verify(string hostname, Javax.Net.Ssl.ISSLSession session)
                {
                    return Javax.Net.Ssl.HttpsURLConnection.DefaultHostnameVerifier.Verify(hostname, session) ||
                        hostname == "10.0.2.2" && session.PeerPrincipal?.Name == "CN=localhost";
                }
            }
        }
#elif IOS
        public bool IsHttpsLocalhost(NSUrlSessionHandler sender, string url, Security.SecTrust trust)
        {
            if (url.StartsWith("https://localhost"))
                return true;
            return false;
        }
#endif
    }

Then invoke it when you create your HttpClient object:

#if DEBUG
            clientHandlerService = new HttpsClientHandlerService();
            client = new HttpClient(clientHandlerService.GetPlatformMessageHandler());
#else
            client = new HttpClient();
#endif

Hopefully this will unblock you.

[AndreduToit]

Hi @davidbritch
Thanks for your almost immediate response and positive recommendations.
I never got as far as to figure out that the network_security_config.xml approach is for HTTP - my bad.
I am going to implement your recommendations and try to unblock - will advise.
Thanks again.

[AndreduToit]

Hello @davidbritch - I am unable to locate IHttpsClientHandlerService - assmebly/namespace - nuget.

[davidbritch]

You could delete that reference (if you want). It's just:

	public interface IHttpsClientHandlerService
	{
        HttpMessageHandler GetPlatformMessageHandler();
    }

[AndreduToit]

@davidbritch
OK, got it thanks.

Can you advise - for HTTPS, do I remove the following:

• Platforms\Android\Resources\raw\kestrel.cer
• Platforms\Android\Resources\xml\network_security_config.xm - as per the suggestion by @Eagle3386.
• line - android:networkSecurityConfig ="@xml/network_security_config" - under tags 'manifest/application' in AndroidManifest.xml

Also, let you know - I tried the same code previously as suggested by @Eilon here dotnet/maui#8131 and provided here: https://gist.github.com/Eilon/49e3c5216abfa3eba81e453d45cba2d4

Did not work before, but I try again. Will let you know.

[AndreduToit]

@davidbritch
Tried your solution and it appears to work, thank you.
Now the hard work begins to figure out what are the differences and why the previous solutions did not work......
Thanks again

[davidbritch]

@AndreduToit

Glad you're unblocked!

Yes, you can remove the following if your localhost service is running over HTTPS:

• Platforms\Android\Resources\raw\kestrel.cer
• Platforms\Android\Resources\xml\network_security_config.xm - as per the suggestion by @Eagle3386.
• line - android:networkSecurityConfig ="@xml/network_security_config" - under tags 'manifest/application' in AndroidManifest.xml

Similarly, you don't need the code-based approach from above if your localhost service is running over HTTP.

[AndreduToit]

@davidbritch thank you for helping me to unblock this - it was super frustrating up to here but I am happy now........ can push ahead.

[Eagle3386]

@davidbritch I'd like to thank you, too, for the clarification about the network_security_config.xml approach as I was once taught it's required for both, HTTP and HTTPS. 😅

Addendum: can you please explain why null instead of new() is return for Windows & Mac Catalyst?
Because that always gives me a NRE upon launching a Windows debug session while everything runs smoothly with the latter.

Additionally, from what I read over at xamarin/xamarin-macios, the NSUrlSessionHandler class is supposed to work on iOS and Mac Catalyst. Why not return the same like for iOS then, e. g. change

#elif IOS

to

#elif IOS || MACCATALYST

[AndreduToit]

@Eagle3386

' why null instead of new() is return for Windows & Mac Catalyst?'

• my guess is that this is because HttpMessageHandler is an abstract class - cannot be instantiated - a subclass is required.

I also found that calling instantiating as follows new HttpClient(null) throws and exception.

For this reason (and because I always enable nullable in my code), I added a property for HttpClient in my helper class - which builds a HttpMessageHandler (GetPlatformMessageHandler) and then on a null test returns either new HttpClient() or new HttpClient(handler)

[davidbritch]

@Eagle3386

Addendum: can you please explain why null instead of new() is return for Windows & Mac Catalyst? Because that always gives me a NRE upon launching a Windows debug session while everything runs smoothly with the latter.

Two things here:

1. I pasted code from my Mac. The version on my Windows machine is the more up to date and has a null check before creating the HttpClient object. But on both machines the HttpsClientHandlerService code is identical.
2. The default HttpClient constructor creates a new HttpClientHandler object which in turns creates the correct underlying platform implementation. So for Windows & MacCatalyst you could return a new HttpClientHandler and pass it to the HttpClient constructor, but that's no different to just doing new HttpClient(). So really it's just a personal choice to return null or a new HttpClientHandler.

Additionally, from what I read over at xamarin/xamarin-macios, the NSUrlSessionHandler class is supposed to work on iOS and Mac Catalyst. Why not return the same like for iOS then

HTTP + HTTPS localhost works out of the box on MacCatalyst, without having to modify NSUrlSessionHandler.

[davidbritch]

@AndreduToit

For this reason (and because I always enable nullable in my code), I added a property for HttpClient in my helper class - which builds a HttpMessageHandler (GetPlatformMessageHandler) and then on a null test returns either new HttpClient() or new HttpClient(handler)

Exactly what I do in the code on my Windows machine (and is the code that will make it into the docs).

[Eagle3386]

@davidbritch

Two things here:

1. I pasted code from my Mac. The version on my Windows machine is the more up to date and has a null check before creating the HttpClient object. But on both machines the HttpsClientHandlerService code is identical.

Understood. Then my approach is just different: I'll return a (new) handler instead of a prepared HttpClient due to my MAUI Blazor app doing normal HTTP requests as HTTP/2 & the SignalR-based stuff as HTTP/1.1 (until SignalR either supports HTTP/2 or even HTTP/3 - which is currently in development, IIRC).

2. (...) So for Windows & MacCatalyst you could return a new HttpClientHandler and pass it to the HttpClient constructor, but that's no different to just doing new HttpClient() (...)

But I've been talking about the "force-pass localhost certs" workaround here & as I said, looking at the aforementioned Xamarin repo's code, iOS & MacCatalyst seem to use the same class, hence overriding TrustOverrideForUrl is required for MacCatalyst (just as is for iOS), isn't it? Because you also say:

HTTP + HTTPS localhost works out of the box on MacCatalyst, without having to modify NSUrlSessionHandler.

And that totally confuses me now.. 😅

[davidbritch]

@Eagle3386

Yes, both iOS + MacCatalyst use NSUrlSessionHandler, and both iOS + MacCatalyst don't trust self-signed certificates by default. However, the self-signed localhost cert in macOS should be marked as trusted (you can look in Keychain Access) because either VSMac has given you a pop up asking if you want to trust the cert, or you've ran the dotnet dev-certs https --trust command.

Hence no need to set the TrustOverrideForUrl property when running on MacCatalyst.

[AndreduToit]

@davidbritch

I share the following for your information and in case someone else can benefit from it.

The code for Verify method of the CustomHostnameVerifier calls suggested by yourself is as follows:

              public bool Verify(string hostname, Javax.Net.Ssl.ISSLSession session)
             {
                    return Javax.Net.Ssl.HttpsURLConnection.DefaultHostnameVerifier.Verify(hostname, session) ||
                        hostname == "10.0.2.2" && session.PeerPrincipal.Name == "CN=localhost";
             }

This code results in some null reference warnings.
I tried the following code, but it does not work - results in 'Hostname 10.0.2.2 not verified' - why? I have no idea :

                public bool Verify(string? hostname, Javax.Net.Ssl.ISSLSession? session)
                {
                    return Javax.Net.Ssl.HttpsURLConnection.DefaultHostnameVerifier?.Verify(hostname, session) ?? false ||
                        hostname == "10.0.2.2" && session?.PeerPrincipal?.Name == "CN=localhost";
                }

The following code seems top be working - without any null reference warnings:

                public bool Verify(string? hostname, Javax.Net.Ssl.ISSLSession? session)
                {
                    if (string.IsNullOrEmpty(hostname) || session == null) return false;
                    var httpsDefaultVerified = Javax.Net.Ssl.HttpsURLConnection.DefaultHostnameVerifier?.Verify(hostname, session) ?? false;
                    var httpsCustomVerified = hostname == "10.0.2.2" && session.PeerPrincipal?.Name == "CN=localhost";
                    return httpsDefaultVerified || httpsCustomVerified;
                }

[simonrozsival]

Just FYI since dotnet/android#7246 was merged, the CustomHostnameVerifier hack won't be necessary in .NET 7 on Android.