GH-287 OpenMaps Implementation (#361) (#404)

* GH-287 Maps Implementation (#361)

* Implemented maps as mentioned in branch name issue. also fixed a spelling mistake

* Added samples

* Added doc stubs

* Added comments for map types

* Refactored code

* Formatting of docs

* Added tests

* Changed coordinates to display something recognisable

* Added uri escaping, thus removing duplicate code. also had to turn off a warning due to inconsistent style cop and vs warning behaviour.

* Removed ref until in is added in c# 7.2

* Adressed issues in pr

* Updated launch code

* Adressed method to onliner

* Updated docs

* Removed ClearTop intent, added sample with adress

* Rename to align names. Added extensions and additional paramaters.

* Update tests

* Throw if options are null.

* Add overload for lat/long without options

DeviceTests/DeviceTests.Shared/DeviceTests.Shared.projitems

@@ -24,6 +24,7 @@
     <Compile Include="$(MSBuildThisFileDirectory)Geocoding_Tests.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Geolocation_Tests.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)MainThread_Tests.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Maps_Tests.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)Permissions_Tests.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)PhoneDialer_Tests.cs" />
     <Compile Include="$(MSBuildThisFileDirectory)ScreenLock_Tests.cs" />

DeviceTests/DeviceTests.Shared/Maps_Tests.cs

@@ -0,0 +1,69 @@
+using System;
+using System.Threading.Tasks;
+using Xamarin.Essentials;
+using Xunit;
+
+namespace DeviceTests
+{
+    public class Maps_Tests
+    {
+        const double testLatitude = 47.645160;
+        const double testLongitude = -122.1306032;
+        const string mapName = "Microsoft Building 25";
+
+        [Fact]
+        [Trait(Traits.InteractionType, Traits.InteractionTypes.Human)]
+        public async Task LaunchMap_CoordinatesDisplayCorrectPlace()
+        {
+            await Maps.OpenAsync(testLatitude, testLongitude, new MapsLaunchOptions { Name = mapName });
+        }
+
+        [Fact]
+        [Trait(Traits.InteractionType, Traits.InteractionTypes.Human)]
+        public async Task LaunchMap_PlacemarkDisplayCorrectPlace()
+        {
+            var placemark = new Placemark
+            {
+                CountryName = "United States",
+                AdminArea = "WA",
+                Thoroughfare = "Microsoft Building 25",
+                Locality = "Redmond"
+            };
+            await Maps.OpenAsync(placemark, new MapsLaunchOptions { Name = mapName });
+        }
+
+        [Fact]
+        public async Task LaunchMap_NullLocation()
+        {
+            Location location = null;
+            await Assert.ThrowsAsync<ArgumentNullException>(() => Maps.OpenAsync(location));
+        }
+
+        [Fact]
+        public async Task LaunchMap_NullOptionsLocation()
+        {
+            var location = new Location(testLatitude, testLongitude);
+            await Assert.ThrowsAsync<ArgumentNullException>(() => Maps.OpenAsync(location, null));
+        }
+
+        [Fact]
+        public async Task LaunchMap_NullPlacemark()
+        {
+            Placemark location = null;
+            await Assert.ThrowsAsync<ArgumentNullException>(() => Maps.OpenAsync(location));
+        }
+
+        [Fact]
+        public async Task LaunchMap_NullOptionsPlacemark()
+        {
+            var placemark = new Placemark
+            {
+                CountryName = "United States",
+                AdminArea = "WA",
+                Thoroughfare = "Microsoft Building 25",
+                Locality = "Redmond"
+            };
+            await Assert.ThrowsAsync<ArgumentNullException>(() => Maps.OpenAsync(placemark, null));
+        }
+    }
+}

Samples/Samples/View/MapsPage.xaml

@@ -0,0 +1,44 @@
+<views:BasePage xmlns="http://xamarin.com/schemas/2014/forms"
+                xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
+                xmlns:views="clr-namespace:Samples.View"
+                xmlns:viewmodels="clr-namespace:Samples.ViewModel"
+                x:Class="Samples.View.MapsPage"
+                Title="Maps">
+    <views:BasePage.BindingContext>
+        <viewmodels:MapsViewModel />
+    </views:BasePage.BindingContext>
+
+    <ScrollView>
+        <StackLayout Padding="10">
+            <Label Text="Open location in maps." FontAttributes="Bold"/>
+
+            <Label Text="Options:"/>
+            <Label Text="Navigation Mode (iOS Only)"/>
+            <Picker HorizontalOptions="FillAndExpand"
+                        ItemsSource="{Binding DirectionModes}"
+                        SelectedIndex="{Binding DirectionMode, Mode=TwoWay}" />
+            <Label Text="Name"/>
+            <Entry Text="{Binding Name}"/>
+                
+                
+
+            <Label Text="Latitude" Margin="0,24,0,0" />
+            <Entry Keyboard="Numeric" Text="{Binding Latitude}" />
+            <Label Text="Longitude" />
+            <Entry Keyboard="Numeric" Text="{Binding Longitude}" />
+            <Button Text="Open coordinates" Command="{Binding MapsCommand}"/>
+
+            <Label Text="Thoroughfare" Margin="0,24,0,0"/>
+            <Entry Text="{Binding Thoroughfare}"/>
+            <Label Text="Locality"/>
+            <Entry Text="{Binding Locality}"/>
+            <Label Text="Admin Area"/>
+            <Entry Text="{Binding AdminArea}"/>
+            <Label Text="Country Name"/>
+            <Entry Text="{Binding Country}"/>
+
+            <Button Text="Open address" Command="{Binding LaunchPlacemarkCommand}"/>
+        </StackLayout>
+    </ScrollView>
+
+</views:BasePage>

Samples/Samples/View/MapsPage.xaml.cs

@@ -0,0 +1,13 @@
+using Xamarin.Forms.Xaml;
+
+namespace Samples.View
+{
+    [XamlCompilation(XamlCompilationOptions.Compile)]
+    public partial class MapsPage : BasePage
+    {
+        public MapsPage()
+        {
+            InitializeComponent();
+        }
+    }
+}

Samples/Samples/ViewModel/HomeViewModel.cs

@@ -126,6 +126,12 @@ namespace Samples.ViewModel
                     typeof(MagnetometerPage),
                     "Detect device's orientation relative to Earth's magnetic field.",
                     new[] { "compass", "magnetometer", "sensors", "hardware", "device" }),
+                new SampleItem(
+                    "📍",
+                    "Launch Maps",
+                    typeof(MapsPage),
+                    "Easily launch maps with coordinates.",
+                    new[] { "geocoding", "geolocation", "position", "address", "mapping", "maps", "route", "navigation" }),
                 new SampleItem(
                     "📏",
                     "Orientation Sensor",

Samples/Samples/ViewModel/MapsViewModel.cs

@@ -0,0 +1,110 @@
+using System.Collections.Generic;
+using System.Windows.Input;
+using Xamarin.Essentials;
+using Xamarin.Forms;
+
+namespace Samples.ViewModel
+{
+    public class MapsViewModel : BaseViewModel
+    {
+        string name = "Microsoft Building 25";
+
+        public string Name
+        {
+            get => name;
+            set => SetProperty(ref name, value);
+        }
+
+        string longitude = "-122.130603";
+
+        public string Longitude
+        {
+            get => longitude;
+            set => SetProperty(ref longitude, value);
+        }
+
+        string latitude = "47.645160";
+
+        public string Latitude
+        {
+            get => latitude;
+            set => SetProperty(ref latitude, value);
+        }
+
+        string locality = "Redmond";
+
+        public string Locality
+        {
+            get => locality;
+            set => SetProperty(ref locality, value);
+        }
+
+        string adminArea = "WA";
+
+        public string AdminArea
+        {
+            get => adminArea;
+            set => SetProperty(ref adminArea, value);
+        }
+
+        string thoroughfare = "Microsoft Building 25";
+
+        public string Thoroughfare
+        {
+            get => thoroughfare;
+            set => SetProperty(ref thoroughfare, value);
+        }
+
+        string country = "United States";
+
+        public string Country
+        {
+            get => country;
+            set => SetProperty(ref country, value);
+        }
+
+        public List<string> DirectionModes { get; } =
+           new List<string>
+           {
+                "Default",
+                "Driving",
+                "Transit",
+                "Walking"
+           };
+
+        int directionMode;
+
+        public int DirectionMode
+        {
+            get => directionMode;
+            set => SetProperty(ref directionMode, value);
+        }
+
+        public ICommand MapsCommand { get; }
+
+        public ICommand LaunchPlacemarkCommand { get; }
+
+        public MapsViewModel()
+        {
+            MapsCommand = new Command(OpenLocation);
+            LaunchPlacemarkCommand = new Command(OpenPlacemark);
+        }
+
+        async void OpenLocation()
+        {
+            await Maps.OpenAsync(double.Parse(Latitude), double.Parse(Longitude), new MapsLaunchOptions { Name = Name, MapDirectionsMode = (MapDirectionsMode)DirectionMode });
+        }
+
+        async void OpenPlacemark()
+        {
+            var placemark = new Placemark
+            {
+                Locality = Locality,
+                AdminArea = AdminArea,
+                CountryName = Country,
+                Thoroughfare = Thoroughfare
+            };
+            await Maps.OpenAsync(placemark, new MapsLaunchOptions() { Name = Name, MapDirectionsMode = (MapDirectionsMode)DirectionMode });
+        }
+    }
+}

Tests/Maps_Tests.cs

@@ -0,0 +1,70 @@
+using System;
+using System.Threading.Tasks;
+using Xamarin.Essentials;
+using Xunit;
+
+namespace Tests
+{
+    public class Maps_Tests
+    {
+        const double testLatitude = 47.645160;
+        const double testLongitude = -122.1306032;
+        const string mapName = "Microsoft Building 25";
+
+        [Fact]
+        public async Task Open_Map_LatLong_NetStandard() =>
+          await Assert.ThrowsAsync<NotImplementedInReferenceAssemblyException>(
+              () => Maps.OpenAsync(
+                  testLatitude,
+                  testLongitude,
+                  new MapsLaunchOptions { Name = mapName }));
+
+        [Fact]
+        public async Task Open_Map_Location_NetStandard() =>
+          await Assert.ThrowsAsync<NotImplementedInReferenceAssemblyException>(
+              () => Maps.OpenAsync(
+                  new Location(testLatitude, testLongitude),
+                  new MapsLaunchOptions { Name = mapName }));
+
+        [Fact]
+        public async Task Open_Map_Placemark_NetStandard() =>
+          await Assert.ThrowsAsync<NotImplementedInReferenceAssemblyException>(
+              () => Maps.OpenAsync(
+                  new Placemark(),
+                  new MapsLaunchOptions { Name = mapName }));
+
+        [Fact]
+        public async Task LaunchMap_NullLocation()
+        {
+            Location location = null;
+            await Assert.ThrowsAsync<ArgumentNullException>(() => Maps.OpenAsync(location));
+        }
+
+        [Fact]
+        public async Task LaunchMap_NullOptionsLocation()
+        {
+            var location = new Location(testLatitude, testLongitude);
+            await Assert.ThrowsAsync<ArgumentNullException>(() => Maps.OpenAsync(location, null));
+        }
+
+        [Fact]
+        public async Task LaunchMap_NullPlacemark()
+        {
+            Placemark location = null;
+            await Assert.ThrowsAsync<ArgumentNullException>(() => Maps.OpenAsync(location));
+        }
+
+        [Fact]
+        public async Task LaunchMap_NullOptionsPlacemark()
+        {
+            var placemark = new Placemark
+            {
+                CountryName = "United States",
+                AdminArea = "WA",
+                Thoroughfare = "Microsoft Building 25",
+                Locality = "Redmond"
+            };
+            await Assert.ThrowsAsync<ArgumentNullException>(() => Maps.OpenAsync(placemark, null));
+        }
+    }
+}

Xamarin.Essentials/Maps/MapDirectionsMode.shared.cs

@@ -0,0 +1,10 @@
+namespace Xamarin.Essentials
+{
+    public enum MapDirectionsMode
+    {
+        Default,
+        Driving,
+        Transit,
+        Walking
+    }
+}

Xamarin.Essentials/Maps/MapLaunchOptions.shared.cs

@@ -0,0 +1,9 @@
+namespace Xamarin.Essentials
+{
+    public class MapsLaunchOptions
+    {
+        public MapDirectionsMode MapDirectionsMode { get; set; } = MapDirectionsMode.Default;
+
+        public string Name { get; set; } = string.Empty;
+    }
+}

Xamarin.Essentials/Maps/Maps.android.cs

@@ -0,0 +1,38 @@
+using System.Globalization;
+using System.Threading.Tasks;
+using Android.Content;
+using AndroidUri = Android.Net.Uri;
+
+namespace Xamarin.Essentials
+{
+    public static partial class Maps
+    {
+        internal static Task PlatformOpenMapsAsync(double latitude, double longitude, MapsLaunchOptions options)
+        {
+            var uri = string.Empty;
+            uri = $"geo:{latitude.ToString(CultureInfo.InvariantCulture)},{longitude.ToString(CultureInfo.InvariantCulture)}?q={latitude.ToString(CultureInfo.InvariantCulture)},{longitude.ToString(CultureInfo.InvariantCulture)}";
+            if (!string.IsNullOrWhiteSpace(options.Name))
+                uri += $"({options.Name})";
+            StartIntent(uri);
+            return Task.CompletedTask;
+        }
+
+        internal static Task PlatformOpenMapsAsync(Placemark placemark, MapsLaunchOptions options)
+        {
+            placemark = placemark.Escape();
+            var uri = $"geo:0,0?q={placemark.Thoroughfare} {placemark.Locality} {placemark.AdminArea} {placemark.CountryName}";
+            if (!string.IsNullOrWhiteSpace(options.Name))
+                uri += $"({options.Name})";
+            StartIntent(uri);
+            return Task.CompletedTask;
+        }
+
+        static void StartIntent(string uri)
+        {
+            var intent = new Intent(Intent.ActionView, AndroidUri.Parse(uri));
+            intent.SetFlags(ActivityFlags.ClearTop);
+            intent.SetFlags(ActivityFlags.NewTask);
+            Platform.AppContext.StartActivity(intent);
+        }
+    }
+}

Xamarin.Essentials/Maps/Maps.ios.cs

@@ -0,0 +1,85 @@
+using System;
+using System.Diagnostics;
+using System.Threading.Tasks;
+using CoreLocation;
+using Foundation;
+using MapKit;
+
+namespace Xamarin.Essentials
+{
+    public static partial class Maps
+    {
+        internal static Task PlatformOpenMapsAsync(double latitude, double longitude, MapsLaunchOptions options)
+        {
+            if (string.IsNullOrWhiteSpace(options.Name))
+                options.Name = string.Empty;
+
+            NSDictionary dictionary = null;
+            var placemark = new MKPlacemark(new CLLocationCoordinate2D(latitude, longitude), dictionary);
+            return OpenPlacemark(placemark, options);
+        }
+
+        internal static async Task PlatformOpenMapsAsync(Placemark placemark, MapsLaunchOptions options)
+        {
+            var address = new MKPlacemarkAddress
+            {
+                CountryCode = placemark.CountryCode,
+                Country = placemark.CountryName,
+                State = placemark.AdminArea,
+                Street = placemark.Thoroughfare,
+                City = placemark.Locality
+            };
+
+            var coder = new CLGeocoder();
+            CLPlacemark[] placemarks = null;
+            try
+            {
+                placemarks = await coder.GeocodeAddressAsync(address.Dictionary);
+            }
+            catch
+            {
+                Debug.WriteLine("Unable to get geocode address from address");
+                return;
+            }
+
+            if ((placemarks?.Length ?? 0) == 0)
+            {
+                Debug.WriteLine("No locations exist, please check address.");
+            }
+
+            await OpenPlacemark(new MKPlacemark(placemarks[0].Location.Coordinate, address), options);
+        }
+
+        static Task OpenPlacemark(MKPlacemark placemark, MapsLaunchOptions options)
+        {
+            var mapItem = new MKMapItem(placemark)
+            {
+                Name = options.Name ?? string.Empty
+            };
+
+            var mode = MKDirectionsMode.Default;
+
+            switch (options.MapDirectionsMode)
+            {
+                case MapDirectionsMode.Driving:
+                    mode = MKDirectionsMode.Driving;
+                    break;
+                case MapDirectionsMode.Transit:
+                    mode = MKDirectionsMode.Transit;
+                    break;
+                case MapDirectionsMode.Walking:
+                    mode = MKDirectionsMode.Walking;
+                    break;
+            }
+
+            var launchOptions = new MKLaunchOptions
+            {
+                DirectionsMode = mode
+            };
+
+            var mapItems = new[] { mapItem };
+            MKMapItem.OpenMaps(mapItems, launchOptions);
+            return Task.CompletedTask;
+        }
+    }
+}

Xamarin.Essentials/Maps/Maps.netstandard.cs

@@ -0,0 +1,13 @@
+using System.Threading.Tasks;
+
+namespace Xamarin.Essentials
+{
+    public static partial class Maps
+    {
+        internal static Task PlatformOpenMapsAsync(double latitude, double longitude, MapsLaunchOptions options)
+            => throw new NotImplementedInReferenceAssemblyException();
+
+        internal static Task PlatformOpenMapsAsync(Placemark placemark, MapsLaunchOptions options)
+            => throw new NotImplementedInReferenceAssemblyException();
+    }
+}

Xamarin.Essentials/Maps/Maps.shared.cs

@@ -0,0 +1,47 @@
+using System;
+using System.Threading.Tasks;
+
+namespace Xamarin.Essentials
+{
+    public static partial class Maps
+    {
+        public static Task OpenAsync(Location location) =>
+            OpenAsync(location, new MapsLaunchOptions());
+
+        public static Task OpenAsync(Location location, MapsLaunchOptions options)
+        {
+            if (location == null)
+                throw new ArgumentNullException(nameof(location));
+
+            if (options == null)
+                throw new ArgumentNullException(nameof(options));
+
+            return PlatformOpenMapsAsync(location.Latitude, location.Longitude, options);
+        }
+
+        public static Task OpenAsync(double latitude, double longitude) =>
+            OpenAsync(latitude, longitude, new MapsLaunchOptions());
+
+        public static Task OpenAsync(double latitude, double longitude, MapsLaunchOptions options)
+        {
+            if (options == null)
+                throw new ArgumentNullException(nameof(options));
+
+            return PlatformOpenMapsAsync(latitude, longitude, options);
+        }
+
+        public static Task OpenAsync(Placemark placemark) =>
+            OpenAsync(placemark, new MapsLaunchOptions());
+
+        public static Task OpenAsync(Placemark placemark, MapsLaunchOptions options)
+        {
+            if (placemark == null)
+                throw new ArgumentNullException(nameof(placemark));
+
+            if (options == null)
+                throw new ArgumentNullException(nameof(options));
+
+            return PlatformOpenMapsAsync(placemark, options);
+        }
+    }
+}

Xamarin.Essentials/Maps/Maps.uwp.cs

@@ -0,0 +1,37 @@
+using System;
+using System.Globalization;
+using System.Threading.Tasks;
+
+namespace Xamarin.Essentials
+{
+    public static partial class Maps
+    {
+        internal static Task PlatformOpenMapsAsync(double latitude, double longitude, MapsLaunchOptions options)
+        {
+            return LaunchUri(new Uri(
+                $"bingmaps:?collection=point." +
+                $"{latitude.ToString(CultureInfo.InvariantCulture)}" +
+                $"_" +
+                $"{longitude.ToString(CultureInfo.InvariantCulture)}" +
+                $"_" +
+                $"{options.Name ?? string.Empty}"));
+        }
+
+        internal static Task PlatformOpenMapsAsync(Placemark placemark, MapsLaunchOptions options)
+        {
+            placemark = placemark.Escape();
+
+            var uri = new Uri(
+                $"bingmaps:?where=" +
+                $"{placemark.Thoroughfare}" +
+                $"%20{placemark.Locality}" +
+                $"%20{placemark.AdminArea}" +
+                $"%20{placemark.CountryName}");
+
+            return LaunchUri(uri);
+        }
+
+        static Task LaunchUri(Uri mapsUri) =>
+            Windows.System.Launcher.LaunchUriAsync(mapsUri).AsTask();
+    }
+}

Xamarin.Essentials/SecureStorage/SecureStorage.android.cs

@@ -177,7 +177,9 @@ namespace Xamarin.Essentials
 
             var end = DateTime.UtcNow.AddYears(20);
             var startDate = new Java.Util.Date();
+#pragma warning disable CS0618 // Type or member is obsolete
             var endDate = new Java.Util.Date(end.Year, end.Month, end.Day);
+#pragma warning restore CS0618 // Type or member is obsolete
 
 #pragma warning disable CS0618
             var builder = new KeyPairGeneratorSpec.Builder(Platform.AppContext)

Xamarin.Essentials/Types/LocationExtensions.shared.cs

@@ -1,8 +1,16 @@
-namespace Xamarin.Essentials
+using System.Threading.Tasks;
+
+namespace Xamarin.Essentials
 {
     public static partial class LocationExtensions
     {
         public static double CalculateDistance(this Location locationStart, Location locationEnd, DistanceUnits units) =>
             Location.CalculateDistance(locationStart, locationEnd, units);
+
+        public static Task OpenMapsAsync(this Location location, MapsLaunchOptions options) =>
+            Maps.OpenAsync(location, options);
+
+        public static Task OpenMapsAsync(this Location location) =>
+            Maps.OpenAsync(location);
     }
 }

Xamarin.Essentials/Types/PlacemarkExtensions.android.cs

@@ -5,7 +5,7 @@ using AndroidAddress = Android.Locations.Address;
 
 namespace Xamarin.Essentials
 {
-    internal static partial class PlacemarkExtensions
+    public static partial class PlacemarkExtensions
     {
         internal static IEnumerable<Placemark> ToPlacemarks(this IEnumerable<AndroidAddress> addresses)
         {

Xamarin.Essentials/Types/PlacemarkExtensions.ios.cs

@@ -4,7 +4,7 @@ using CoreLocation;
 
 namespace Xamarin.Essentials
 {
-    internal static partial class PlacemarkExtensions
+    public static partial class PlacemarkExtensions
     {
         internal static IEnumerable<Placemark> ToPlacemarks(this IEnumerable<CLPlacemark> addresses)
         {

Xamarin.Essentials/Types/PlacemarkExtensions.shared.cs

@@ -1,6 +1,38 @@
-namespace Xamarin.Essentials
+using System;
+using System.Threading.Tasks;
+
+namespace Xamarin.Essentials
 {
-    internal static partial class PlacemarkExtensions
+    public static partial class PlacemarkExtensions
     {
+        public static Task OpenMapsAsync(this Placemark placemark, MapsLaunchOptions options) =>
+            Maps.OpenAsync(placemark, options);
+
+        public static Task OpenMapsAsync(this Placemark placemark) =>
+            Maps.OpenAsync(placemark);
+
+        internal static Placemark Escape(this Placemark placemark)
+        {
+            if (placemark == null)
+                throw new ArgumentNullException(nameof(placemark));
+            var escaped = new Placemark();
+
+            if (placemark.Location == null)
+                escaped.Location = new Location();
+            else
+                escaped.Location = new Location(placemark.Location);
+
+            escaped.CountryCode = string.IsNullOrWhiteSpace(placemark.CountryCode) ? string.Empty : Uri.EscapeUriString(placemark.CountryCode);
+            escaped.CountryName = string.IsNullOrWhiteSpace(placemark.CountryName) ? string.Empty : Uri.EscapeUriString(placemark.CountryName);
+            escaped.FeatureName = string.IsNullOrWhiteSpace(placemark.FeatureName) ? string.Empty : Uri.EscapeUriString(placemark.FeatureName);
+            escaped.PostalCode = string.IsNullOrWhiteSpace(placemark.PostalCode) ? string.Empty : Uri.EscapeUriString(placemark.PostalCode);
+            escaped.Locality = string.IsNullOrWhiteSpace(placemark.Locality) ? string.Empty : Uri.EscapeUriString(placemark.Locality);
+            escaped.SubLocality = string.IsNullOrWhiteSpace(placemark.SubLocality) ? string.Empty : Uri.EscapeUriString(placemark.SubLocality);
+            escaped.Thoroughfare = string.IsNullOrWhiteSpace(placemark.Thoroughfare) ? string.Empty : Uri.EscapeUriString(placemark.Thoroughfare);
+            escaped.SubThoroughfare = string.IsNullOrWhiteSpace(placemark.SubThoroughfare) ? string.Empty : Uri.EscapeUriString(placemark.SubThoroughfare);
+            escaped.SubAdminArea = string.IsNullOrWhiteSpace(placemark.SubAdminArea) ? string.Empty : Uri.EscapeUriString(placemark.SubAdminArea);
+            escaped.AdminArea = string.IsNullOrWhiteSpace(placemark.AdminArea) ? string.Empty : Uri.EscapeUriString(placemark.AdminArea);
+            return escaped;
+        }
     }
 }

Xamarin.Essentials/Xamarin.Essentials.csproj

@@ -45,7 +45,7 @@
   </PropertyGroup>
   <ItemGroup>
     <None Include="..\nugetreadme.txt" PackagePath="readme.txt" Pack="true" />
-    <PackageReference Include="mdoc" Version="5.7.1" PrivateAssets="All" />
+    <PackageReference Include="mdoc" Version="5.7.2" PrivateAssets="All" />
     <PackageReference Include="MSBuild.Sdk.Extras" Version="1.6.41" PrivateAssets="All" />
     <PackageReference Include="System.Numerics.Vectors" Version="4.5.0" />
     <Compile Include="**\*.shared.cs" />

Xamarin.Essentials/mdoc.targets

@@ -39,7 +39,7 @@
       <FileWrites Include="$(MDocOutputPath)" />
     </ItemGroup>
     <Exec Condition=" '$(_ShouldGenerateDocs)' == 'true' "
-          Command="$(_ManagedExeLauncher) &quot;$(MDocToolPath)&quot; export-msxdoc --out=&quot;$(MDocOutputPath)&quot; &quot;$(MDocDocumentationDirectory)&quot;" />
+          Command="$(_ManagedExeLauncher) &quot;$(MDocToolPath)&quot; export-msxdoc --debug --out=&quot;$(MDocOutputPath)&quot; &quot;$(MDocDocumentationDirectory)&quot;" />
   </Target>
 
   <!--

docs/en/FrameworksIndex/xamarin-essentials-android.xml

@@ -239,6 +239,8 @@
     </Type>
     <Type Name="Xamarin.Essentials.LocationExtensions" Id="T:Xamarin.Essentials.LocationExtensions">
       <Member Id="M:Xamarin.Essentials.LocationExtensions.CalculateDistance(Xamarin.Essentials.Location,Xamarin.Essentials.Location,Xamarin.Essentials.DistanceUnits)" />
+      <Member Id="M:Xamarin.Essentials.LocationExtensions.OpenMapsAsync(Xamarin.Essentials.Location)" />
+      <Member Id="M:Xamarin.Essentials.LocationExtensions.OpenMapsAsync(Xamarin.Essentials.Location,Xamarin.Essentials.MapsLaunchOptions)" />
     </Type>
     <Type Name="Xamarin.Essentials.Magnetometer" Id="T:Xamarin.Essentials.Magnetometer">
       <Member Id="E:Xamarin.Essentials.Magnetometer.ReadingChanged" />
@@ -256,6 +258,24 @@
       <Member Id="M:Xamarin.Essentials.MainThread.BeginInvokeOnMainThread(System.Action)" />
       <Member Id="P:Xamarin.Essentials.MainThread.IsMainThread" />
     </Type>
+    <Type Name="Xamarin.Essentials.MapDirectionsMode" Id="T:Xamarin.Essentials.MapDirectionsMode">
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Default" />
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Driving" />
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Transit" />
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Walking" />
+    </Type>
+    <Type Name="Xamarin.Essentials.Maps" Id="T:Xamarin.Essentials.Maps">
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(System.Double,System.Double,Xamarin.Essentials.MapsLaunchOptions)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Location)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Location,Xamarin.Essentials.MapsLaunchOptions)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Placemark)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Placemark,Xamarin.Essentials.MapsLaunchOptions)" />
+    </Type>
+    <Type Name="Xamarin.Essentials.MapsLaunchOptions" Id="T:Xamarin.Essentials.MapsLaunchOptions">
+      <Member Id="M:Xamarin.Essentials.MapsLaunchOptions.#ctor" />
+      <Member Id="P:Xamarin.Essentials.MapsLaunchOptions.MapDirectionsMode" />
+      <Member Id="P:Xamarin.Essentials.MapsLaunchOptions.Name" />
+    </Type>
     <Type Name="Xamarin.Essentials.NetworkAccess" Id="T:Xamarin.Essentials.NetworkAccess">
       <Member Id="F:Xamarin.Essentials.NetworkAccess.ConstrainedInternet" />
       <Member Id="F:Xamarin.Essentials.NetworkAccess.Internet" />
@@ -299,6 +319,10 @@
       <Member Id="P:Xamarin.Essentials.Placemark.SubThoroughfare" />
       <Member Id="P:Xamarin.Essentials.Placemark.Thoroughfare" />
     </Type>
+    <Type Name="Xamarin.Essentials.PlacemarkExtensions" Id="T:Xamarin.Essentials.PlacemarkExtensions">
+      <Member Id="M:Xamarin.Essentials.PlacemarkExtensions.OpenMapsAsync(Xamarin.Essentials.Placemark)" />
+      <Member Id="M:Xamarin.Essentials.PlacemarkExtensions.OpenMapsAsync(Xamarin.Essentials.Placemark,Xamarin.Essentials.MapsLaunchOptions)" />
+    </Type>
     <Type Name="Xamarin.Essentials.Platform" Id="T:Xamarin.Essentials.Platform">
       <Member Id="M:Xamarin.Essentials.Platform.Init(Android.App.Activity,Android.OS.Bundle)" />
       <Member Id="M:Xamarin.Essentials.Platform.Init(Android.App.Application)" />

docs/en/FrameworksIndex/xamarin-essentials-ios.xml

@@ -240,6 +240,8 @@
     </Type>
     <Type Name="Xamarin.Essentials.LocationExtensions" Id="T:Xamarin.Essentials.LocationExtensions">
       <Member Id="M:Xamarin.Essentials.LocationExtensions.CalculateDistance(Xamarin.Essentials.Location,Xamarin.Essentials.Location,Xamarin.Essentials.DistanceUnits)" />
+      <Member Id="M:Xamarin.Essentials.LocationExtensions.OpenMapsAsync(Xamarin.Essentials.Location)" />
+      <Member Id="M:Xamarin.Essentials.LocationExtensions.OpenMapsAsync(Xamarin.Essentials.Location,Xamarin.Essentials.MapsLaunchOptions)" />
     </Type>
     <Type Name="Xamarin.Essentials.Magnetometer" Id="T:Xamarin.Essentials.Magnetometer">
       <Member Id="E:Xamarin.Essentials.Magnetometer.ReadingChanged" />
@@ -257,6 +259,24 @@
       <Member Id="M:Xamarin.Essentials.MainThread.BeginInvokeOnMainThread(System.Action)" />
       <Member Id="P:Xamarin.Essentials.MainThread.IsMainThread" />
     </Type>
+    <Type Name="Xamarin.Essentials.MapDirectionsMode" Id="T:Xamarin.Essentials.MapDirectionsMode">
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Default" />
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Driving" />
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Transit" />
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Walking" />
+    </Type>
+    <Type Name="Xamarin.Essentials.Maps" Id="T:Xamarin.Essentials.Maps">
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(System.Double,System.Double,Xamarin.Essentials.MapsLaunchOptions)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Location)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Location,Xamarin.Essentials.MapsLaunchOptions)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Placemark)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Placemark,Xamarin.Essentials.MapsLaunchOptions)" />
+    </Type>
+    <Type Name="Xamarin.Essentials.MapsLaunchOptions" Id="T:Xamarin.Essentials.MapsLaunchOptions">
+      <Member Id="M:Xamarin.Essentials.MapsLaunchOptions.#ctor" />
+      <Member Id="P:Xamarin.Essentials.MapsLaunchOptions.MapDirectionsMode" />
+      <Member Id="P:Xamarin.Essentials.MapsLaunchOptions.Name" />
+    </Type>
     <Type Name="Xamarin.Essentials.NetworkAccess" Id="T:Xamarin.Essentials.NetworkAccess">
       <Member Id="F:Xamarin.Essentials.NetworkAccess.ConstrainedInternet" />
       <Member Id="F:Xamarin.Essentials.NetworkAccess.Internet" />
@@ -300,6 +320,10 @@
       <Member Id="P:Xamarin.Essentials.Placemark.SubThoroughfare" />
       <Member Id="P:Xamarin.Essentials.Placemark.Thoroughfare" />
     </Type>
+    <Type Name="Xamarin.Essentials.PlacemarkExtensions" Id="T:Xamarin.Essentials.PlacemarkExtensions">
+      <Member Id="M:Xamarin.Essentials.PlacemarkExtensions.OpenMapsAsync(Xamarin.Essentials.Placemark)" />
+      <Member Id="M:Xamarin.Essentials.PlacemarkExtensions.OpenMapsAsync(Xamarin.Essentials.Placemark,Xamarin.Essentials.MapsLaunchOptions)" />
+    </Type>
     <Type Name="Xamarin.Essentials.Platform" Id="T:Xamarin.Essentials.Platform" />
     <Type Name="Xamarin.Essentials.Power" Id="T:Xamarin.Essentials.Power">
       <Member Id="E:Xamarin.Essentials.Power.EnergySaverStatusChanged" />

docs/en/FrameworksIndex/xamarin-essentials-uwp.xml

@@ -239,6 +239,8 @@
     </Type>
     <Type Name="Xamarin.Essentials.LocationExtensions" Id="T:Xamarin.Essentials.LocationExtensions">
       <Member Id="M:Xamarin.Essentials.LocationExtensions.CalculateDistance(Xamarin.Essentials.Location,Xamarin.Essentials.Location,Xamarin.Essentials.DistanceUnits)" />
+      <Member Id="M:Xamarin.Essentials.LocationExtensions.OpenMapsAsync(Xamarin.Essentials.Location)" />
+      <Member Id="M:Xamarin.Essentials.LocationExtensions.OpenMapsAsync(Xamarin.Essentials.Location,Xamarin.Essentials.MapsLaunchOptions)" />
     </Type>
     <Type Name="Xamarin.Essentials.Magnetometer" Id="T:Xamarin.Essentials.Magnetometer">
       <Member Id="E:Xamarin.Essentials.Magnetometer.ReadingChanged" />
@@ -256,6 +258,24 @@
       <Member Id="M:Xamarin.Essentials.MainThread.BeginInvokeOnMainThread(System.Action)" />
       <Member Id="P:Xamarin.Essentials.MainThread.IsMainThread" />
     </Type>
+    <Type Name="Xamarin.Essentials.MapDirectionsMode" Id="T:Xamarin.Essentials.MapDirectionsMode">
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Default" />
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Driving" />
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Transit" />
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Walking" />
+    </Type>
+    <Type Name="Xamarin.Essentials.Maps" Id="T:Xamarin.Essentials.Maps">
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(System.Double,System.Double,Xamarin.Essentials.MapsLaunchOptions)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Location)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Location,Xamarin.Essentials.MapsLaunchOptions)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Placemark)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Placemark,Xamarin.Essentials.MapsLaunchOptions)" />
+    </Type>
+    <Type Name="Xamarin.Essentials.MapsLaunchOptions" Id="T:Xamarin.Essentials.MapsLaunchOptions">
+      <Member Id="M:Xamarin.Essentials.MapsLaunchOptions.#ctor" />
+      <Member Id="P:Xamarin.Essentials.MapsLaunchOptions.MapDirectionsMode" />
+      <Member Id="P:Xamarin.Essentials.MapsLaunchOptions.Name" />
+    </Type>
     <Type Name="Xamarin.Essentials.NetworkAccess" Id="T:Xamarin.Essentials.NetworkAccess">
       <Member Id="F:Xamarin.Essentials.NetworkAccess.ConstrainedInternet" />
       <Member Id="F:Xamarin.Essentials.NetworkAccess.Internet" />
@@ -299,6 +319,10 @@
       <Member Id="P:Xamarin.Essentials.Placemark.SubThoroughfare" />
       <Member Id="P:Xamarin.Essentials.Placemark.Thoroughfare" />
     </Type>
+    <Type Name="Xamarin.Essentials.PlacemarkExtensions" Id="T:Xamarin.Essentials.PlacemarkExtensions">
+      <Member Id="M:Xamarin.Essentials.PlacemarkExtensions.OpenMapsAsync(Xamarin.Essentials.Placemark)" />
+      <Member Id="M:Xamarin.Essentials.PlacemarkExtensions.OpenMapsAsync(Xamarin.Essentials.Placemark,Xamarin.Essentials.MapsLaunchOptions)" />
+    </Type>
     <Type Name="Xamarin.Essentials.Platform" Id="T:Xamarin.Essentials.Platform" />
     <Type Name="Xamarin.Essentials.Power" Id="T:Xamarin.Essentials.Power">
       <Member Id="E:Xamarin.Essentials.Power.EnergySaverStatusChanged" />

docs/en/FrameworksIndex/xamarin-essentials.xml

@@ -239,6 +239,8 @@
     </Type>
     <Type Name="Xamarin.Essentials.LocationExtensions" Id="T:Xamarin.Essentials.LocationExtensions">
       <Member Id="M:Xamarin.Essentials.LocationExtensions.CalculateDistance(Xamarin.Essentials.Location,Xamarin.Essentials.Location,Xamarin.Essentials.DistanceUnits)" />
+      <Member Id="M:Xamarin.Essentials.LocationExtensions.OpenMapsAsync(Xamarin.Essentials.Location)" />
+      <Member Id="M:Xamarin.Essentials.LocationExtensions.OpenMapsAsync(Xamarin.Essentials.Location,Xamarin.Essentials.MapsLaunchOptions)" />
     </Type>
     <Type Name="Xamarin.Essentials.Magnetometer" Id="T:Xamarin.Essentials.Magnetometer">
       <Member Id="E:Xamarin.Essentials.Magnetometer.ReadingChanged" />
@@ -256,6 +258,24 @@
       <Member Id="M:Xamarin.Essentials.MainThread.BeginInvokeOnMainThread(System.Action)" />
       <Member Id="P:Xamarin.Essentials.MainThread.IsMainThread" />
     </Type>
+    <Type Name="Xamarin.Essentials.MapDirectionsMode" Id="T:Xamarin.Essentials.MapDirectionsMode">
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Default" />
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Driving" />
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Transit" />
+      <Member Id="F:Xamarin.Essentials.MapDirectionsMode.Walking" />
+    </Type>
+    <Type Name="Xamarin.Essentials.Maps" Id="T:Xamarin.Essentials.Maps">
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(System.Double,System.Double,Xamarin.Essentials.MapsLaunchOptions)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Location)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Location,Xamarin.Essentials.MapsLaunchOptions)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Placemark)" />
+      <Member Id="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Placemark,Xamarin.Essentials.MapsLaunchOptions)" />
+    </Type>
+    <Type Name="Xamarin.Essentials.MapsLaunchOptions" Id="T:Xamarin.Essentials.MapsLaunchOptions">
+      <Member Id="M:Xamarin.Essentials.MapsLaunchOptions.#ctor" />
+      <Member Id="P:Xamarin.Essentials.MapsLaunchOptions.MapDirectionsMode" />
+      <Member Id="P:Xamarin.Essentials.MapsLaunchOptions.Name" />
+    </Type>
     <Type Name="Xamarin.Essentials.NetworkAccess" Id="T:Xamarin.Essentials.NetworkAccess">
       <Member Id="F:Xamarin.Essentials.NetworkAccess.ConstrainedInternet" />
       <Member Id="F:Xamarin.Essentials.NetworkAccess.Internet" />
@@ -299,6 +319,10 @@
       <Member Id="P:Xamarin.Essentials.Placemark.SubThoroughfare" />
       <Member Id="P:Xamarin.Essentials.Placemark.Thoroughfare" />
     </Type>
+    <Type Name="Xamarin.Essentials.PlacemarkExtensions" Id="T:Xamarin.Essentials.PlacemarkExtensions">
+      <Member Id="M:Xamarin.Essentials.PlacemarkExtensions.OpenMapsAsync(Xamarin.Essentials.Placemark)" />
+      <Member Id="M:Xamarin.Essentials.PlacemarkExtensions.OpenMapsAsync(Xamarin.Essentials.Placemark,Xamarin.Essentials.MapsLaunchOptions)" />
+    </Type>
     <Type Name="Xamarin.Essentials.Platform" Id="T:Xamarin.Essentials.Platform" />
     <Type Name="Xamarin.Essentials.Power" Id="T:Xamarin.Essentials.Power">
       <Member Id="E:Xamarin.Essentials.Power.EnergySaverStatusChanged" />

docs/en/Xamarin.Essentials/LocationExtensions.xml

@@ -45,5 +45,51 @@
         </remarks>
       </Docs>
     </Member>
+    <Member MemberName="OpenMapsAsync">
+      <MemberSignature Language="C#" Value="public static System.Threading.Tasks.Task OpenMapsAsync (this Xamarin.Essentials.Location location);" />
+      <MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Threading.Tasks.Task OpenMapsAsync(class Xamarin.Essentials.Location location) cil managed" />
+      <MemberSignature Language="DocId" Value="M:Xamarin.Essentials.LocationExtensions.OpenMapsAsync(Xamarin.Essentials.Location)" />
+      <MemberType>Method</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>System.Threading.Tasks.Task</ReturnType>
+      </ReturnValue>
+      <Parameters>
+        <Parameter Name="location" Type="Xamarin.Essentials.Location" RefType="this" />
+      </Parameters>
+      <Docs>
+        <param name="location">To be added.</param>
+        <summary>To be added.</summary>
+        <returns>To be added.</returns>
+        <remarks>To be added.</remarks>
+      </Docs>
+    </Member>
+    <Member MemberName="OpenMapsAsync">
+      <MemberSignature Language="C#" Value="public static System.Threading.Tasks.Task OpenMapsAsync (this Xamarin.Essentials.Location location, Xamarin.Essentials.MapsLaunchOptions options);" />
+      <MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Threading.Tasks.Task OpenMapsAsync(class Xamarin.Essentials.Location location, class Xamarin.Essentials.MapsLaunchOptions options) cil managed" />
+      <MemberSignature Language="DocId" Value="M:Xamarin.Essentials.LocationExtensions.OpenMapsAsync(Xamarin.Essentials.Location,Xamarin.Essentials.MapsLaunchOptions)" />
+      <MemberType>Method</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>System.Threading.Tasks.Task</ReturnType>
+      </ReturnValue>
+      <Parameters>
+        <Parameter Name="location" Type="Xamarin.Essentials.Location" RefType="this" />
+        <Parameter Name="options" Type="Xamarin.Essentials.MapsLaunchOptions" />
+      </Parameters>
+      <Docs>
+        <param name="location">To be added.</param>
+        <param name="options">To be added.</param>
+        <summary>To be added.</summary>
+        <returns>To be added.</returns>
+        <remarks>To be added.</remarks>
+      </Docs>
+    </Member>
   </Members>
 </Type>

docs/en/Xamarin.Essentials/MapDirectionsMode.xml

@@ -0,0 +1,86 @@
+<Type Name="MapDirectionsMode" FullName="Xamarin.Essentials.MapDirectionsMode">
+  <TypeSignature Language="C#" Value="public enum MapDirectionsMode" />
+  <TypeSignature Language="ILAsm" Value=".class public auto ansi sealed MapDirectionsMode extends System.Enum" />
+  <TypeSignature Language="DocId" Value="T:Xamarin.Essentials.MapDirectionsMode" />
+  <AssemblyInfo>
+    <AssemblyName>Xamarin.Essentials</AssemblyName>
+    <AssemblyVersion>1.0.0.0</AssemblyVersion>
+  </AssemblyInfo>
+  <Base>
+    <BaseTypeName>System.Enum</BaseTypeName>
+  </Base>
+  <Docs>
+    <summary>To be added.</summary>
+    <remarks>To be added.</remarks>
+  </Docs>
+  <Members>
+    <Member MemberName="Default">
+      <MemberSignature Language="C#" Value="Default" />
+      <MemberSignature Language="ILAsm" Value=".field public static literal valuetype Xamarin.Essentials.MapDirectionsMode Default = int32(0)" />
+      <MemberSignature Language="DocId" Value="F:Xamarin.Essentials.MapDirectionsMode.Default" />
+      <MemberType>Field</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>Xamarin.Essentials.MapDirectionsMode</ReturnType>
+      </ReturnValue>
+      <MemberValue>0</MemberValue>
+      <Docs>
+        <summary>The default MapDirectionsMode on your platform.</summary>
+      </Docs>
+    </Member>
+    <Member MemberName="Driving">
+      <MemberSignature Language="C#" Value="Driving" />
+      <MemberSignature Language="ILAsm" Value=".field public static literal valuetype Xamarin.Essentials.MapDirectionsMode Driving = int32(1)" />
+      <MemberSignature Language="DocId" Value="F:Xamarin.Essentials.MapDirectionsMode.Driving" />
+      <MemberType>Field</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>Xamarin.Essentials.MapDirectionsMode</ReturnType>
+      </ReturnValue>
+      <MemberValue>1</MemberValue>
+      <Docs>
+        <summary>Car route mode.</summary>
+      </Docs>
+    </Member>
+    <Member MemberName="Transit">
+      <MemberSignature Language="C#" Value="Transit" />
+      <MemberSignature Language="ILAsm" Value=".field public static literal valuetype Xamarin.Essentials.MapDirectionsMode Transit = int32(2)" />
+      <MemberSignature Language="DocId" Value="F:Xamarin.Essentials.MapDirectionsMode.Transit" />
+      <MemberType>Field</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>Xamarin.Essentials.MapDirectionsMode</ReturnType>
+      </ReturnValue>
+      <MemberValue>2</MemberValue>
+      <Docs>
+        <summary>Transit route mode.</summary>
+      </Docs>
+    </Member>
+    <Member MemberName="Walking">
+      <MemberSignature Language="C#" Value="Walking" />
+      <MemberSignature Language="ILAsm" Value=".field public static literal valuetype Xamarin.Essentials.MapDirectionsMode Walking = int32(3)" />
+      <MemberSignature Language="DocId" Value="F:Xamarin.Essentials.MapDirectionsMode.Walking" />
+      <MemberType>Field</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>Xamarin.Essentials.MapDirectionsMode</ReturnType>
+      </ReturnValue>
+      <MemberValue>3</MemberValue>
+      <Docs>
+        <summary>Walking route mode.</summary>
+      </Docs>
+    </Member>
+  </Members>
+</Type>

docs/en/Xamarin.Essentials/Maps.xml

@@ -0,0 +1,139 @@
+<Type Name="Maps" FullName="Xamarin.Essentials.Maps">
+  <TypeSignature Language="C#" Value="public static class Maps" />
+  <TypeSignature Language="ILAsm" Value=".class public auto ansi abstract sealed beforefieldinit Maps extends System.Object" />
+  <TypeSignature Language="DocId" Value="T:Xamarin.Essentials.Maps" />
+  <AssemblyInfo>
+    <AssemblyName>Xamarin.Essentials</AssemblyName>
+    <AssemblyVersion>1.0.0.0</AssemblyVersion>
+  </AssemblyInfo>
+  <Base>
+    <BaseTypeName>System.Object</BaseTypeName>
+  </Base>
+  <Interfaces />
+  <Docs>
+    <summary>Map helpers to open a route to specified places via default platforms maps implementation.</summary>
+    <remarks>
+      <para />
+    </remarks>
+  </Docs>
+  <Members>
+    <Member MemberName="OpenAsync">
+      <MemberSignature Language="C#" Value="public static System.Threading.Tasks.Task OpenAsync (Xamarin.Essentials.Location location);" />
+      <MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Threading.Tasks.Task OpenAsync(class Xamarin.Essentials.Location location) cil managed" />
+      <MemberSignature Language="DocId" Value="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Location)" />
+      <MemberType>Method</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>System.Threading.Tasks.Task</ReturnType>
+      </ReturnValue>
+      <Parameters>
+        <Parameter Name="location" Type="Xamarin.Essentials.Location" />
+      </Parameters>
+      <Docs>
+        <param name="location">To be added.</param>
+        <summary>To be added.</summary>
+        <returns>To be added.</returns>
+        <remarks>To be added.</remarks>
+      </Docs>
+    </Member>
+    <Member MemberName="OpenAsync">
+      <MemberSignature Language="C#" Value="public static System.Threading.Tasks.Task OpenAsync (Xamarin.Essentials.Placemark placemark);" />
+      <MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Threading.Tasks.Task OpenAsync(class Xamarin.Essentials.Placemark placemark) cil managed" />
+      <MemberSignature Language="DocId" Value="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Placemark)" />
+      <MemberType>Method</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>System.Threading.Tasks.Task</ReturnType>
+      </ReturnValue>
+      <Parameters>
+        <Parameter Name="placemark" Type="Xamarin.Essentials.Placemark" />
+      </Parameters>
+      <Docs>
+        <param name="placemark">To be added.</param>
+        <summary>To be added.</summary>
+        <returns>To be added.</returns>
+        <remarks>To be added.</remarks>
+      </Docs>
+    </Member>
+    <Member MemberName="OpenAsync">
+      <MemberSignature Language="C#" Value="public static System.Threading.Tasks.Task OpenAsync (Xamarin.Essentials.Location location, Xamarin.Essentials.MapsLaunchOptions options);" />
+      <MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Threading.Tasks.Task OpenAsync(class Xamarin.Essentials.Location location, class Xamarin.Essentials.MapsLaunchOptions options) cil managed" />
+      <MemberSignature Language="DocId" Value="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Location,Xamarin.Essentials.MapsLaunchOptions)" />
+      <MemberType>Method</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>System.Threading.Tasks.Task</ReturnType>
+      </ReturnValue>
+      <Parameters>
+        <Parameter Name="location" Type="Xamarin.Essentials.Location" />
+        <Parameter Name="options" Type="Xamarin.Essentials.MapsLaunchOptions" />
+      </Parameters>
+      <Docs>
+        <param name="location">To be added.</param>
+        <param name="options">To be added.</param>
+        <summary>To be added.</summary>
+        <returns>To be added.</returns>
+        <remarks>To be added.</remarks>
+      </Docs>
+    </Member>
+    <Member MemberName="OpenAsync">
+      <MemberSignature Language="C#" Value="public static System.Threading.Tasks.Task OpenAsync (Xamarin.Essentials.Placemark placemark, Xamarin.Essentials.MapsLaunchOptions options);" />
+      <MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Threading.Tasks.Task OpenAsync(class Xamarin.Essentials.Placemark placemark, class Xamarin.Essentials.MapsLaunchOptions options) cil managed" />
+      <MemberSignature Language="DocId" Value="M:Xamarin.Essentials.Maps.OpenAsync(Xamarin.Essentials.Placemark,Xamarin.Essentials.MapsLaunchOptions)" />
+      <MemberType>Method</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>System.Threading.Tasks.Task</ReturnType>
+      </ReturnValue>
+      <Parameters>
+        <Parameter Name="placemark" Type="Xamarin.Essentials.Placemark" />
+        <Parameter Name="options" Type="Xamarin.Essentials.MapsLaunchOptions" />
+      </Parameters>
+      <Docs>
+        <param name="placemark">To be added.</param>
+        <param name="options">To be added.</param>
+        <summary>To be added.</summary>
+        <returns>To be added.</returns>
+        <remarks>To be added.</remarks>
+      </Docs>
+    </Member>
+    <Member MemberName="OpenAsync">
+      <MemberSignature Language="C#" Value="public static System.Threading.Tasks.Task OpenAsync (double latitude, double longitude, Xamarin.Essentials.MapsLaunchOptions options);" />
+      <MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Threading.Tasks.Task OpenAsync(float64 latitude, float64 longitude, class Xamarin.Essentials.MapsLaunchOptions options) cil managed" />
+      <MemberSignature Language="DocId" Value="M:Xamarin.Essentials.Maps.OpenAsync(System.Double,System.Double,Xamarin.Essentials.MapsLaunchOptions)" />
+      <MemberType>Method</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>System.Threading.Tasks.Task</ReturnType>
+      </ReturnValue>
+      <Parameters>
+        <Parameter Name="latitude" Type="System.Double" />
+        <Parameter Name="longitude" Type="System.Double" />
+        <Parameter Name="options" Type="Xamarin.Essentials.MapsLaunchOptions" />
+      </Parameters>
+      <Docs>
+        <param name="latitude">To be added.</param>
+        <param name="longitude">To be added.</param>
+        <param name="options">To be added.</param>
+        <summary>To be added.</summary>
+        <returns>To be added.</returns>
+        <remarks>To be added.</remarks>
+      </Docs>
+    </Member>
+  </Members>
+</Type>

docs/en/Xamarin.Essentials/MapsLaunchOptions.xml

@@ -0,0 +1,70 @@
+<Type Name="MapsLaunchOptions" FullName="Xamarin.Essentials.MapsLaunchOptions">
+  <TypeSignature Language="C#" Value="public class MapsLaunchOptions" />
+  <TypeSignature Language="ILAsm" Value=".class public auto ansi beforefieldinit MapsLaunchOptions extends System.Object" />
+  <TypeSignature Language="DocId" Value="T:Xamarin.Essentials.MapsLaunchOptions" />
+  <AssemblyInfo>
+    <AssemblyName>Xamarin.Essentials</AssemblyName>
+    <AssemblyVersion>1.0.0.0</AssemblyVersion>
+  </AssemblyInfo>
+  <Base>
+    <BaseTypeName>System.Object</BaseTypeName>
+  </Base>
+  <Interfaces />
+  <Docs>
+    <summary>To be added.</summary>
+    <remarks>To be added.</remarks>
+  </Docs>
+  <Members>
+    <Member MemberName=".ctor">
+      <MemberSignature Language="C#" Value="public MapsLaunchOptions ();" />
+      <MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor() cil managed" />
+      <MemberSignature Language="DocId" Value="M:Xamarin.Essentials.MapsLaunchOptions.#ctor" />
+      <MemberType>Constructor</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <Parameters />
+      <Docs>
+        <summary>To be added.</summary>
+        <remarks>To be added.</remarks>
+      </Docs>
+    </Member>
+    <Member MemberName="MapDirectionsMode">
+      <MemberSignature Language="C#" Value="public Xamarin.Essentials.MapDirectionsMode MapDirectionsMode { get; set; }" />
+      <MemberSignature Language="ILAsm" Value=".property instance valuetype Xamarin.Essentials.MapDirectionsMode MapDirectionsMode" />
+      <MemberSignature Language="DocId" Value="P:Xamarin.Essentials.MapsLaunchOptions.MapDirectionsMode" />
+      <MemberType>Property</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>Xamarin.Essentials.MapDirectionsMode</ReturnType>
+      </ReturnValue>
+      <Docs>
+        <summary>To be added.</summary>
+        <value>To be added.</value>
+        <remarks>To be added.</remarks>
+      </Docs>
+    </Member>
+    <Member MemberName="Name">
+      <MemberSignature Language="C#" Value="public string Name { get; set; }" />
+      <MemberSignature Language="ILAsm" Value=".property instance string Name" />
+      <MemberSignature Language="DocId" Value="P:Xamarin.Essentials.MapsLaunchOptions.Name" />
+      <MemberType>Property</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>System.String</ReturnType>
+      </ReturnValue>
+      <Docs>
+        <summary>To be added.</summary>
+        <value>To be added.</value>
+        <remarks>To be added.</remarks>
+      </Docs>
+    </Member>
+  </Members>
+</Type>

docs/en/Xamarin.Essentials/Placemark.xml

@@ -267,7 +267,7 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets or sets the streen name.</summary>
+        <summary>Gets or sets the street name.</summary>
         <value>The street name.</value>
         <remarks>
           <para></para>

docs/en/Xamarin.Essentials/PlacemarkExtensions.xml

@@ -0,0 +1,65 @@
+<Type Name="PlacemarkExtensions" FullName="Xamarin.Essentials.PlacemarkExtensions">
+  <TypeSignature Language="C#" Value="public static class PlacemarkExtensions" />
+  <TypeSignature Language="ILAsm" Value=".class public auto ansi abstract sealed beforefieldinit PlacemarkExtensions extends System.Object" />
+  <TypeSignature Language="DocId" Value="T:Xamarin.Essentials.PlacemarkExtensions" />
+  <AssemblyInfo>
+    <AssemblyName>Xamarin.Essentials</AssemblyName>
+    <AssemblyVersion>1.0.0.0</AssemblyVersion>
+  </AssemblyInfo>
+  <Base>
+    <BaseTypeName>System.Object</BaseTypeName>
+  </Base>
+  <Interfaces />
+  <Docs>
+    <summary>To be added.</summary>
+    <remarks>To be added.</remarks>
+  </Docs>
+  <Members>
+    <Member MemberName="OpenMapsAsync">
+      <MemberSignature Language="C#" Value="public static System.Threading.Tasks.Task OpenMapsAsync (this Xamarin.Essentials.Placemark placemark);" />
+      <MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Threading.Tasks.Task OpenMapsAsync(class Xamarin.Essentials.Placemark placemark) cil managed" />
+      <MemberSignature Language="DocId" Value="M:Xamarin.Essentials.PlacemarkExtensions.OpenMapsAsync(Xamarin.Essentials.Placemark)" />
+      <MemberType>Method</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>System.Threading.Tasks.Task</ReturnType>
+      </ReturnValue>
+      <Parameters>
+        <Parameter Name="placemark" Type="Xamarin.Essentials.Placemark" RefType="this" />
+      </Parameters>
+      <Docs>
+        <param name="placemark">To be added.</param>
+        <summary>To be added.</summary>
+        <returns>To be added.</returns>
+        <remarks>To be added.</remarks>
+      </Docs>
+    </Member>
+    <Member MemberName="OpenMapsAsync">
+      <MemberSignature Language="C#" Value="public static System.Threading.Tasks.Task OpenMapsAsync (this Xamarin.Essentials.Placemark placemark, Xamarin.Essentials.MapsLaunchOptions options);" />
+      <MemberSignature Language="ILAsm" Value=".method public static hidebysig class System.Threading.Tasks.Task OpenMapsAsync(class Xamarin.Essentials.Placemark placemark, class Xamarin.Essentials.MapsLaunchOptions options) cil managed" />
+      <MemberSignature Language="DocId" Value="M:Xamarin.Essentials.PlacemarkExtensions.OpenMapsAsync(Xamarin.Essentials.Placemark,Xamarin.Essentials.MapsLaunchOptions)" />
+      <MemberType>Method</MemberType>
+      <AssemblyInfo>
+        <AssemblyName>Xamarin.Essentials</AssemblyName>
+        <AssemblyVersion>1.0.0.0</AssemblyVersion>
+      </AssemblyInfo>
+      <ReturnValue>
+        <ReturnType>System.Threading.Tasks.Task</ReturnType>
+      </ReturnValue>
+      <Parameters>
+        <Parameter Name="placemark" Type="Xamarin.Essentials.Placemark" RefType="this" />
+        <Parameter Name="options" Type="Xamarin.Essentials.MapsLaunchOptions" />
+      </Parameters>
+      <Docs>
+        <param name="placemark">To be added.</param>
+        <param name="options">To be added.</param>
+        <summary>To be added.</summary>
+        <returns>To be added.</returns>
+        <remarks>To be added.</remarks>
+      </Docs>
+    </Member>
+  </Members>
+</Type>

docs/en/Xamarin.Essentials/TextToSpeech.xml

@@ -67,6 +67,14 @@
         <AssemblyName>Xamarin.Essentials</AssemblyName>
         <AssemblyVersion>1.0.0.0</AssemblyVersion>
       </AssemblyInfo>
+      <Attributes>
+        <Attribute>
+          <AttributeName>System.Diagnostics.DebuggerStepThrough</AttributeName>
+        </Attribute>
+        <Attribute>
+          <AttributeName>System.Runtime.CompilerServices.AsyncStateMachine(typeof(Xamarin.Essentials.TextToSpeech/&lt;SpeakAsync&gt;d__9))</AttributeName>
+        </Attribute>
+      </Attributes>
       <ReturnValue>
         <ReturnType>System.Threading.Tasks.Task</ReturnType>
       </ReturnValue>

docs/en/index.xml

@@ -107,6 +107,9 @@
       <Type Name="MagnetometerChangedEventArgs" Kind="Class" />
       <Type Name="MagnetometerData" Kind="Structure" />
       <Type Name="MainThread" Kind="Class" />
+      <Type Name="MapDirectionsMode" Kind="Enumeration" />
+      <Type Name="Maps" Kind="Class" />
+      <Type Name="MapsLaunchOptions" Kind="Class" />
       <Type Name="NetworkAccess" Kind="Enumeration" />
       <Type Name="NotImplementedInReferenceAssemblyException" Kind="Class" />
       <Type Name="OrientationSensor" Kind="Class" />
@@ -115,6 +118,7 @@
       <Type Name="PermissionException" Kind="Class" />
       <Type Name="PhoneDialer" Kind="Class" />
       <Type Name="Placemark" Kind="Class" />
+      <Type Name="PlacemarkExtensions" Kind="Class" />
       <Type Name="Platform" Kind="Class" />
       <Type Name="Power" Kind="Class" />
       <Type Name="Preferences" Kind="Class" />
@@ -134,33 +138,4 @@
       <Type Name="Vibration" Kind="Class" />
     </Namespace>
   </Types>
-  <Title>Untitled</Title>
-  <ExtensionMethods>
-    <ExtensionMethod>
-      <Targets>
-        <Target Type="T:Xamarin.Essentials.Location" />
-      </Targets>
-      <Member MemberName="CalculateDistance">
-        <MemberSignature Language="C#" Value="public static double CalculateDistance (this Xamarin.Essentials.Location locationStart, Xamarin.Essentials.Location locationEnd, Xamarin.Essentials.DistanceUnits units);" />
-        <MemberSignature Language="ILAsm" Value=".method public static hidebysig float64 CalculateDistance(class Xamarin.Essentials.Location locationStart, class Xamarin.Essentials.Location locationEnd, valuetype Xamarin.Essentials.DistanceUnits units) cil managed" />
-        <MemberSignature Language="DocId" Value="M:Xamarin.Essentials.LocationExtensions.CalculateDistance(Xamarin.Essentials.Location,Xamarin.Essentials.Location,Xamarin.Essentials.DistanceUnits)" />
-        <MemberType>ExtensionMethod</MemberType>
-        <ReturnValue>
-          <ReturnType>System.Double</ReturnType>
-        </ReturnValue>
-        <Parameters>
-          <Parameter Name="locationStart" Type="Xamarin.Essentials.Location" RefType="this" />
-          <Parameter Name="locationEnd" Type="Xamarin.Essentials.Location" />
-          <Parameter Name="units" Type="Xamarin.Essentials.DistanceUnits" />
-        </Parameters>
-        <Docs>
-          <param name="locationStart">Start location to calculate from.</param>
-          <param name="locationEnd">End location to calculate from.</param>
-          <param name="units">Units to use during calculation.</param>
-          <summary>Extension to calculate distance from location to another location.</summary>
-        </Docs>
-        <Link Type="Xamarin.Essentials.LocationExtensions" Member="M:Xamarin.Essentials.LocationExtensions.CalculateDistance(Xamarin.Essentials.Location,Xamarin.Essentials.Location,Xamarin.Essentials.DistanceUnits)" />
-      </Member>
-    </ExtensionMethod>
-  </ExtensionMethods>
 </Overview>