GeolocatorService.Reactive 0.2.0-dev.45

This is a prerelease version of GeolocatorService.Reactive.
There is a newer version of this package available.
See the version list below for details.
dotnet add package GeolocatorService.Reactive --version 0.2.0-dev.45                
NuGet\Install-Package GeolocatorService.Reactive -Version 0.2.0-dev.45                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="GeolocatorService.Reactive" Version="0.2.0-dev.45" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add GeolocatorService.Reactive --version 0.2.0-dev.45                
#r "nuget: GeolocatorService.Reactive, 0.2.0-dev.45"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install GeolocatorService.Reactive as a Cake Addin
#addin nuget:?package=GeolocatorService.Reactive&version=0.2.0-dev.45&prerelease

// Install GeolocatorService.Reactive as a Cake Tool
#tool nuget:?package=GeolocatorService.Reactive&version=0.2.0-dev.45&prerelease                

GeolocatorService

License Version Downloads

A service to get the user's current location, based on Geolocator, suited to WinUI, UWP or Uno apps.

GeolocatorService aims to simplify getting the user's current location and handling most common scenarios, including getting the permission to obtain this location and handling cases where this permission is denied.

Getting Started

  1. Add Package

    .Net Mobile / WinUI

    Add the GeolocatorService.Uno.WinUI nuget package to your project heads.

    To have access to reactive extensions such as GetAndObserveLocation, add the GeolocatorService.Reactive.Uno.WinUI nuget package to your project.

    Xamarin / UWP

    Add the GeolocatorService nuget package to your project heads.

    To have access to reactive extensions such as GetAndObserveLocation, add the GeolocatorService.Reactive nuget package to your project.

  2. Add the relevant permissions

    Windows

    Add the Location capability in your manifest.

    
     <Package ...>
    
         <Capabilities>
             <DeviceCapability Name="location"/>
         </Capabilities>
     </Package>
    

    <details> <summary>Visual Studio appxmanisfest UI</summary>

    appxmanifest </details>

    iOS

    Include the NSLocationWhenInUsageDescription and NSLocationUsageDescription entries in your info.plist file. These values define the message shown to users when they are asked for location permission. For instance,

    
     <key>NSLocationWhenInUseUsageDescription</key>
     <string>TODO NSLocationWhenInUsageDescription</string>
     <key>NSLocationUsageDescription</key>
     <string>TODO NSLocationUsageDescription</string>
    
    Android

    Add the location permission to your AssemblyInfo.cs file.

     // AssemblyInfo.cs
     [assembly: UsesPermission(Android.Manifest.Permission.AccessFineLocation)]
    
  3. Instantiate GeolocatorService

    Add GeoLocatorService :

    var locationService = new GeoLocatorService();
    
  4. Request permission

    After you have added the relevant location permission info to your project configuration, locate the spot in your code where you want to ask the user for their location permission. This iOS guidelines or this Android guidelines may help you decide. This must be done before accessing their location. Add the following line to do so:

    var isGranted = await locationService.RequestPermission(CancellationToken.None);
    
  5. Request User location

    If permission is granted, you are able to invoke the GetLocation function to obtain the user's current location.

    Geocoordinate location = await locationService.GetLocation(CancellationToken.None);
    

Features

Request Permission

   var isGranted = await locationService.RequestPermission(CancellationToken.None);

You may safely request the permission multiple times; the user will only get prompted as often as is necessary.

For instance, if you ask the user for their permission once and they decline, calling RequestPermission again will not prompt the user again, but simply return false.

If the user answers "Allow once", then calling RequestPermission again during the lifetime of the app will simply return true. Once the app is restarted, calling RequestPermission will prompt them for the permission once again, since their original permission has now expired.

Once permission is requested, you can use the various methods and extension methods of IGeolocatorService.

Request the user's location

Once you have obtained the location permission, it's a simple matter to obtain the location:

if (isGranted)
{
    location = await locationService.GetLocation(CancellationToken.None);
}
//or
var locationOrDefault = await locationService.GetLocationOrDefault(CancellationToken.None);

When using GetLocation, if the user has not granted the location permission, an InvalidOperationException is thrown; therefore, we recommend not calling this method if you know the user has denied the location permission and this is a normal scenario.

In cases you are not sure of the permission status, we suggest employing the extension method named GetLocationOrDefault instead. This method will return null instead of throwing an exception, in case the permission was denied.

React to changes in the user's location or their permissions

IGeolocatorService offers events to allow you to react when the user's location has changed, or when they have granted or denied permissions. Even if these changes occur while the app is in background, they will be raised when the app comes back to the foreground.

locationService.LocationChanged += OnLocationChanged;
locationService.LocationPermissionChanged += OnLocationPermissionChanged;

Track the location and permission using Reactive Extensions

GeolocatorService.Reactive adds a few extension methods which will allow your app to fluidly keep track of the user's location and permission status.

For instance, let's say your app wants to display relevant information to the user's location when it's available, and a completely different type of information when that location is unavailable (because the permission was denied or the device is unable to provide a location).

IObservable<PageContent> content = locationService.GetAndObserveLocationOrDefault(ct)
    .Select(location =>
    {
        if (location == null)
        {
            // TODO Gets information which is independent of the location
        }
        else
        {
            // TODO Gets information pertinent to the location
        }
    });

Geocoordinate

Please note that the value generated from a user's location depends on the capabilities of the platform. Not all devices can provide information such as Altitude, Heading (direction), and Speed.

Geocoordinates offer details about the Accuracy of the data. Additionally, you can access the source of the data through PositionSource. This information can help you evaluate the precision of the collected data.

Breaking Changes

Please consult the BREAKING CHANGES for more information about breaking changes history.

Changelog

Please consult the CHANGELOG for more information about version history.

License

This project is licensed under the Apache 2.0 license - see the LICENSE file for details.

Contributing

Please read CONTRIBUTING.md for details on the process for contributing to this project.

Be mindful of our Code of Conduct.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed.  monoandroid12.0 is compatible. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Universal Windows Platform uap10.0.19041 is compatible. 
Xamarin.iOS xamarinios was computed.  xamarinios10 is compatible. 
Xamarin.Mac xamarinmac was computed.  xamarinmac20 is compatible. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.0 124 3/8/2024
0.2.0-feature.Uno5Update.49 174 11/6/2023
0.2.0-dev.dotnet6.33 156 9/26/2022
0.2.0-dev.dotnet6.31 131 9/26/2022
0.2.0-dev.45 55 10/19/2023
0.2.0-dev.43 87 3/24/2023
0.2.0-dev.41 401 10/13/2022
0.2.0-dev.29 5,181 8/25/2022
0.2.0-dev.26 118 8/23/2022
0.2.0-dev.19 9,662 12/13/2021
0.2.0-dev.17 165 12/8/2021