xamarin/essentials

Essential cross platform APIs for your mobile apps.

Xamarin.Essentials

Xamarin.Essentials gives developers essential cross-platform APIs for their mobile applications.

iOS, Android, and UWP offer unique operating system and platform APIs that developers have access to, all in C# leveraging Xamarin. It is great that developers have 100% API access in C# with Xamarin, but these APIs are different per platform. This means developers have to learn three different APIs to access platform-specific features. With Xamarin.Essentials, developers have a single cross-platform API that works with any iOS, Android, or UWP application that can be accessed from shared code no matter how the user interface is created.

Questions

Get your technical questions answered by experts on Microsoft Q&A.

Contribution Discussion

Contributing to Xamarin.Essentials? Join our Discord server and chat with the team

Build Status

Build Server	Type	Platform	Status
Azure DevOps	Build	Windows

Installation

Xamarin.Essentials is available via NuGet & is included in every template:

• NuGet Official Releases:
• Nightly / CI Releases: https://aka.ms/xamarin-essentials-ci/index.json

Please read our Getting Started with Xamarin.Essentials guide for full setup instructions.

Xamarin.Essentials with .NET MAUI and iOS/Android .NET projects

Starting in .NET 6, Xamarin.Essentials was added into .NET MAUI directly. The team has worked hard to ensure that while it comes pre-configured with every .NET MAUI application, it is still available to all iOS and Android apps built with .NET. If you are building a .NET MAUI project there is nothing more for you to do, just start using the APIs. If you are migrating a Xamarin.iOS or Xamarin.Android app and want to use the Essentials APIs, then add the following into your project's csproj file:

<PropertyGroup>
  <UseMauiEssentials>true</UseMauiEssentials>
</PropertyGroup>

Once you update to .NET MAUI Essentials, you will need to update any using Xamarin.Essentials; using statements (and any other namespace references) to the new .NET MAUI Essentials namespaces, which you can find in the documentation.

Documentation

Browse our full documentation for Xamarin.Essentials, including feature guides, on how to use each feature.

Supported Platforms

Platform support & feature support can be found on our documentation

Contributing

Please read through our Contribution Guide. We are not accepting new PRs for full features, however any issue that is marked as up for grabs are open for community contributions. We encourage creating new issues for bugs found during usage that the team will triage. Additionally, we are open for code refactoring suggestions in PRs.

Building Xamarin.Essentials

Xamarin.Essentials is built with the new SDK-style projects with multi-targeting enabled. This means that all code for iOS, Android, and UWP exist inside of the Xamarin.Essentials project.

Visual Studio

A minimum version of Visual Studio 2019 16.3 or Visual Studio for Mac 2019 8.3 are required to build and compile Xamarin.Essentials.

Workloads needed:

• Xamarin
• .NET Core
• UWP

You will need the following SDKs

• Android 10.0, 9.0, 8.1, 8.0, 7.1, 7.0, & 6.0 SDK Installed
• UWP 10.0.16299 SDK Installed

Your can run the included android-setup.ps1 script in Administrator Mode and it will automatically setup your Android environment.

FAQ

Here are some frequently asked questions about Xamarin.Essentials, but be sure to read our full FAQ on our Wiki.

License

Please see the License.

Stats

essentials's Issues

Clipboard API's

Clipboard manipulation:

class Clipboard {
    void SetText(string text);
    void SetText(string text, string label);
    bool HasText { get; }
    Task<string> GetTextAsync();
}

• UWP: https://docs.microsoft.com/en-us/windows/uwp/app-to-app/copy-and-paste
• Android: https://developer.android.com/reference/android/content/ClipboardManager.html
• iOS https://developer.apple.com/documentation/uikit/uipasteboard

Rename NotImplentedInReferenceAssembly to NotImplentedInReferenceAssemblyException

Description

All exceptions should end in "Exception"

UI/Main Thread Invoke API

UIThreadRunInvoker class offers unified API for calling methods on Main/UI thread from background threads (async methods).

UIThreadRunInvoker.BeginOnUIThread(Action action);

calls:

• on Android

Platform.CurrentActivity(Action action);

• on iOS

UIKit.UIAPplication.SharedApplication.BeginInvokeOnMainThread(Action action);

To investigate is call to CoreFoundation.DispatchQueue.MainQueue.DispatchAsync(Action)

• on UWP

Windows.ApplicationModel.Core.CoreAPplication.MainView.CoreWindow.Dispatcher.RunAsync(Action)

Next steps (if API survives) is to add overloads for Func<> arguments/parameters...

NuGet author must be Microsoft

Bug report best practices: Submitting Issues

Description

Steps to Reproduce

1. Look at the author field of the nuspec

Expected Behavior

<Authors>Microsoft</Authors>

Actual Behavior

<Authors>Xamarin Inc.</Authors>

Text-To-Speech API's

Make devices speak arbitrary text

TextToSpeech

public static class TextToSpeech
{
    public static int MaxSpeechInputLength { get; }

    public static Task SpeakAsync (string text, CancellationToken cancelToken = default(CancellationToken));
    public static Task SpeakAsync (string text, SpeakSettings settings, CancellationToken cancelToken = default(CancellationToken));

    public static Task GetLocalesAsync ();
}

SpeakSettings (struct)

public struct SpeakSettings
{
    public Locale Locale;
    public float? Pitch;
    public float? SpeakRate;
    public float? Volume;
}

Locale

public static class Locale
{
    public string Language { get; }
    public string Country { get; }
    public string Name { get; }
}

Platform API's

Some platforms will require some sort of initialization or otherwise platform specific calls. This is the area they should be dealt with.

Platform - Android Only

public static class Platform
{
    internal static Activity CurrentActivity { get; }
    internal static Context CurrentContext { get; }

    // Should be called from the MainActivity in general
    public static void Init (Activity activity, Bundle bundle);

    // Should be called from the activity where permission requests occurred
    public static void OnRequestPermissionsResult (int requestCode, string[] permissions, Permission[] grantResults);
}

DeviceInfo needs a way to get the ID

This may either be the unique device identifier and/or the installation Id.

APIs:

• iOS: identifierForVendor This is a unique ID for all of a vendors apps installed on the device.
• Android: Build.Serial now replaced in API 26 with Build.GetSerial() not every manufacturer fills this out though and previously I used the Secure.AndroidId
• UWP: GetSystemIdForPublisher with backup of GetPackageSpecificToken

If you are leave a comment here can you please describe why and how you are using it.

Geolocation API's

The Geolocation API is meant to be extremely simple at this point.

Geocoding API's: #28

static class Geolocation {
    // Android and iOS have a concept of a last known position that should return very quickly compared to firing up the GPS and waiting for a position.
    // This should return null if there is no known last position.
    // UWP has something interesting about consent-less location:
    // https://docs.microsoft.com/en-us/uwp/api/Windows.Devices.Geolocation.Geolocator#Windows_Devices_Geolocation_Geolocator_AllowFallbackToConsentlessPositions
    static Task<Position> GetLastKnownPositionAsync();

    // We should throw different exceptions depending on the error: For example a DeviceFeatureUnavailableException or something similar if the device has no GPS abilities.
    static Task<Position> GetPositionAsync(GeolocationAccuracy desiredAccuracy, TimeSpan timeout, CancellationToken token = default(CancellationToken));
}

class Position {
    Position();
    Position(double latitude, double longitude);
    Position(double latitude, double longitude, DateTimeOffset timestamp);
    Position(Position position);

    DateTimeOffset Timestamp { get; set; }
    double Latitude { get; set; }
    double Longitude { get; set; }

    static double CalculateDistance(Position positionStart, Position positionEnd);
    static double CalculateDistance(
        double latitudeStart, double latitudeEnd, 
        double longitudeStart, double longitudeEnd);
}

enum GeolocationAccuracy {
    Lowest,
    Low,
    Medium,
    High,
    Best
}

The accuracy enum values should map to the following table of platform specific accuracy choices:

	iOS	Expected	Android	Expected	UWP	Expected
Lowest	ThreeKilometers	3000	ACCURACY_LOW, POWER_LOW	500	3000	1000-5000
Low	Kilometer	1000	ACCURACY_LOW, POWER_MEDIUM	500	1000	300-3000
Medium	HundredMeters	100	ACCURACY_MEDIUM, POWER_MEDIUM	100-500	100	30-500
High	NearestTenMeters	10	ACCURACY_HIGH, POWER_MEDIUM	0-100	High	<=10
Best	Best	0	ACCURACY_HIGH, POWER_HIGH	0-100	High	<=10

class GeolocationException {
    GeolocationException(GeolocationErrorType errorType);
    GeolocationException(GeolocationErrorType, Exception innerException);

    GeolocationErrorType ErrorType { get; }
}

enum GeolocationErrorType {
    PositionUnavailable,
    Unauthorized
}

Battery API's

Simple battery % and charging state.

class Battery {
    // range from [0.0, 1.0]
    // -1 is unknown or invalid
    double ChargeLevel { get; }

    BatteryState State { get; }

    event EventHandler<BatteryChangedEventArgs> BatteryChanged;
}

class BatteryChangedEventArgs : EventArgs {
    ctor(double level, BatteryStatus status);

    double ChargeLevel { get; }
    BatteryState State { get; }
}

enum BatteryState {
    Unknown,
    Charging,
    Discharging,
    Full,
    NotCharging
}

Native platform features:

Platform	State
iOS	unknown, unplugged, charging, full
Android	charging, discharging, full, notCharging, unknown
UWP	charging, discharging, idle, notPresent

iOS Notes:

• Discharging can be mapped from unplugged.
• NotCharging can be ignored.

UWP Notes:

• NotCharging can be mapped from idle.
• Full can be mapped if ChargeLevel >= 100.
• Unknown can be mapped if ChargeLevel <= 0 || notPresent

Battery - UWP returns notcharging when full and plugged in

Description

Steps to Reproduce

1. Have surface fully charged and plugged in
2. API reports NotCharging
3. API returns Power source battery

Expected Behavior

Report Full

Actual Behavior

NotCharging Returned

Detect Shake API

Would we want to have an API that detects if the user shakes the device?

VS bug #735682

PRs accepted?

I see that keystore/keychain is planned -- I have an implementation of this done for iOS/Android, and I don't think it would take much effort to add UWP. Wasn't sure how far along on that you were or if perhaps this feature was meant for something larger (like Xamarin.Auth), but if you're just looking for the basic keystore/keychain implementation im happy to send a PR :-)

API Review: BeginInvokeOnMainThread

Discussion:

Should it be called BeginInvokeOnMainThread or InvokeOnMainThread

Via C# docs:

• Delegate.Invoke: Executes synchronously, on the same thread.
• Delegate.BeginInvoke: Executes asynchronously, on a threadpool thread.
• Control.Invoke: Executes on the UI thread, but calling thread waits for completion before continuing.
• Control.BeginInvoke: Executes on the UI thread, and calling thread doesn't wait for completion.

API Review to ensure we do what we say:
Today we are:

• Android: Post to looper
• iOS: calls BeginInvokeOnMainThread and calls (action.Invoke)
• uwp we run async on the dispatcher

Messaging API's

Issues moved to #25 (phone dialler), #26 (sms), #27 (email)

Connectivity API's

A really simple way to check if we have an internet connection.

Connectivity

Properties

• bool IsConnected (readonly)
• IEnumerable ConnectionTypes (readonly)

Events

• EventHandler ConnectivityChanged
• EventHandler ConnectivityTypeChanged

ConnectionType (enum)

• Cellular
• WiFi
• Desktop
• Wimax
• Other
• Bluetooth

ConnectivityChangedEventArgs : EventArgs

Constructors

• ConnectivityChangedEventArgs (bool isConnected)

Properties

• bool IsConnected (readonly)

ConnectivityTypeChangedEventArgs : ConnectivityChangedEventArgs

Constructors

• ConnectivityTypeChangedEventArgs (bool isConnected, IEnumerable types)

Properties

• IEnumerable ConnectionTypes (readonly)

Flashlight API

Description

API for turning on and off Flashlight

API

static class Flashlight
{
    static void On();
    static void Off();

    static FlashlightState State { get; }
}

enum FlashlightState
{
    Unknown,
    On,
    Off
}

Vibration API

Vibration API

A simple API to make the device vibrate with the given settings.

Move Application info into "AppInfo" class

Description

Right now we have DeviceInfo, which also holds a bunch of information about the Application too.

This way we can have:

AppInfo.Version and DeviceInfo.Version :)

Would be really nice.

Tizen support

Are you interested in Tizen support?
As I can see more and more xam-plugins now supports tizen platform.

Biometrics API

Fingerprint API

Description

API for Fingerprint scanning.

VS bug #735680

PhoneDialer API's

A simple API to open the default dialer, preloaded with a number and name.

static class PhoneDialer {
    static bool IsSupported { get; }
    // should throw a NotSupportedOnDeviceException if the device is not capable.
    static void Open(string number);
}

For the discussion around exceptions, see #19

NFC API

NFC API

Read only API - iOS allows only reading NDEF tags.

• Android: Android.Nfc
• iOS: CoreNFC
• UWP:

Device Info API's

Basic information about a Device and its Operating system.

DeviceInfo

Properties

• string Model (readonly)
• string Manufacturer (readonly)
• string DeviceName (readonly)
• string Version (readonly)
• Version VersionNumber (readonly)
• string AppVersion (readonly)
• string AppBuild (readonly)
• string Platform (readonly)

  These values returned will match those which Xamarin.Forms uses.

• string Idiom (readonly)
• bool IsDevice (readonly)

DeviceInfo.Idioms

Consts

• string Car = nameof (Car)
• string Desktop = nameof (Desktop)
• string Phone = nameof (Phone)
• string Tablet = nameof (Tablet)
• string Television = nameof (Television)
• string Watch = nameof (Watch)

DeviceInfo.Platforms

Consts

• string Android = nameof (Android)
• string iOS = nameof (iOS)
• string UWP = “Windows” // must match Forms

Contributing doc needs mdoc tutorial

The CONTRIBUTING.md file needs some information about our usage of mdoc and how to do an mdoc update, as well as what is expected on pull requests with mdoc.

Sensors API Compass

Sensors APIs (Compass, Accelerometer, Gyroscope, Magnetometer)

INPROGRESS

MDocs required for existing implementations

We are missing mdocs for some earlier implementation code:

• Platform
• Battery
• Device Info
• Geocoding
• Permissions
• Platform
• Preferences

Browser API's

Open links in browser (shell out to native, or use embedded system browser), with some customizability.

Some discussed points:

• Only implement what most browsers support (no custom views, buttons, etc)
• Colors are OK to implement
• Android Support CustomTabs dependency is ok

Filesystem Helper API's

Some simple and helpful abstractions for common Filesystem problems

static class FileSystem {
    // Returns a path to a directory that can be used to temporarily store data.
    // Potentially cleared by the user (eg: on Android in the device settings) or by the OS when space runs low.
    static string CacheDirectory { get; }

    // Returns a path to a directory that contains app data.
    // This directory may not be visible to the user.
    static string AppDataDirectory { get; }

    // Returns a path to a directory that contains user-visible data.
    // This directory may be visible/editable to the user.
    static string UserDataDirectory { get; }

    // Opens a file Stream to a file embedded in the app package.
    //     Android: Asset
    //     iOS: NSBundle.MainBundle
    //     UWP: Package.InstalledLocation
    static Task<Stream> OpenAppPackageFileAsync(string filename);
}

Storage Secure API

Storage Secure (Secured) API

Platform	Implementation
Android	KeyStore
iOS	KeyChain
UWP	StorageFile + DataProtectionProvider

1. Task<string> LoadAsync(string filename)
2. Task SaveAsync(string filename, string content)

[Android] Sms doesn't work if recepient isn't filled out

Description

The logic does not set the sms_body if the recipient isn't filled out.

Steps to Reproduce

1. Launch sample
2. Go to SMS
3. Fill in only body

Expected Behavior

Should open sms app and have body filled in

Actual Behavior

Default Sms app opens

Basic Information

• Version with issue: Latest
• Last known good version: None
• IDE: VS2017
• Platform Target Frameworks:
  • Android: Nougat tested

Extra info:

https://gist.github.com/mustafasevgi/8c6b638ffd5fca90d45d may be the better route here.

Add quick introduction to project structure

Please add a quick introduction about how solution is structured.
The multi-targeting libraries are new to lot of people, a contribution guide will help greatly for new contributors

Update Remarks in Docs with possible exceptions

• App Information
• Battery
• Clipboard
• Data Transfer
• Device Information
• File System Helpers
• Geocoding
• Open Browser
• Preferences
• Screen Lock
• SMS

Screenshot API

Would we want a Screenshot of the current window/screen?

VS bug #735683

Exceptions

There are some patterns in several API's that we might want to have some common exception types for.

Feature Availability

Things like GPS, Cameras, Phone, SMS, etc are not always available on a given device. When a method is called which tries to make use of such a device, we should throw a consistent exception to let the developer know the feature is unsupported on the current device:

NotSupportedOnDeviceException : NotSupportedException

There may also be the case where a feature is technically supported by the device, but not enabled:

NotEnabledOnDeviceException : InvalidOperationException

Open to ideas on naming, and other common exceptions we may require...

Feature/Capability Availability/Status API's

There's been a lot of discussion around handling checking of device capabilities and feature availability at runtime. This should be a central place to formulate our strategy around these types of API's.

Keep in mind we want to grow the API surface as conservatively as possible. Once an API is public in our first stable release, it lives forever.

We also want to remember that the reason for adding any API's is to make developers' experiences delightful in consuming our library.

Purpose

The purpose of any sort of Status or Availability query on a feature is to see if it's usable or not when called. This means in almost every case, the developer doesn't really care about the actual state of availability, but rather that they can use the feature.

There's one exception to this: When something might be unavailable, but could be made available through code (eg: prompting the user, etc).

NOTE: This is not to be confused with missing or lack of granted permissions for a feature.

Strategies

Capabilities class

One strategy was to introduce a Capabilities class. I dislike this strategy for a couple of reasons:

1. It's separated from the actual class being used, and much less discoverable. If I'm working with Location, if while I'm typing Location. I see Location.Availability, it might prompt me with the idea that I should or at least could check to see if the feature works at runtime before using it.
2. Capabilities is in a sense tightly coupled to pretty much every other class.

One suggestion is we could have a property in each class which just calls into the Capabilities class. I also dislike this idea as it introduces ambiguity (we'll end up with people writing code like if (Geolocation.IsAvailable && Capabilities.HasGeolocation) to be safe. It also means more code paths to test and maintain.

Exceptions

Regardless of the strategy we use around checking for feature/capability availability, users won't be required to check these before attempting to use them, so we will still need to throw exceptions such as NotSupportedException at runtime if a particular API is unavailable at the time of invocation.

So, the exception strategy is to simply omit any API for checking availability and have the developer rely on exception handling to detect when things are not supported or available.

The benefit to this approach is we can always add other API's for checking availability down the road as this exception work will be done regardless.

Where this approach becomes a bit messy is with statuses where a developer may be able to do something to enable or have the user enable a feature and try again. For example, this becomes a bit messy:

Position p;

try {
    p = await Geolocation.GetPositionAsync ();
} catch (GeolocationDisabledException) {
    // Prompt user to enable geolocation
    await DoSomethingToGetTheUserToEnable ();

    // Try getting location again
    try {
        p = await Geolocation.GetPositionAsync ();
    } catch (Exception ex) {
        // Not gonna happen
    }
}

Status or Availability properties

Given the purpose of these API's, most cases where such an availability API would be useful could be distilled down to mostly a true/false basis. However, we want to avoid bool still as using an enum allows for more possible values in the future if necessary.

Most cases could use a simple enum such as:

public enum SmsStatus {
	Unavailable,
	Ready
}

And the class would implement a simple property:

public static partial class Sms {
	public static SmsStatus Status { get; }
}

In cases where we might want to provide another status to indicate something is unavailable but may be able to be made available we would introduce another status value:

public enum GeolocationStatus {
	Unavailable,
	Disabled,
	Ready
}

And the class implements:

public static partial class Geolocation {
	public static GeolocationStatus Status { get; }
}

In this case, GeolocationStatus.Disabled would indicate to the developer that the device may be capable of providing location data, but that feature is for some reason disabled (perhaps the user turned off location services on android). This could be a queue for the developer to prompt the user to enable location services.

There are also other possibilities for the naming convention here:

• Status
• Availability
• SupportLevel

VS bug #735684

Table of Device/Simulator Support

Geocoding API's

A simple way to convert from a position to an address.

Geolocation API's: #7

_NOTE: the Position type is used from #7 _

static class Geocoding {
    // Requires a map key string on UWP
    // should throw an exception on UWP if this isn’t specified via the static MapKey property.
    static Task<IEnumerable<Address>> GetAddressesAsync(Position position);
    static Task<IEnumerable<Position>> GetPositionsForAddressAsync(string address);
}

// UWP-only partial
static class Geocoding {
    // UWP Only, and should only be in the UWP assembly
    // Users can call `Geolocation.MapKey = "blah"` from their UWP specific code (like where Inits are called).
    static string MapKey { get; set; }
}

class Address{
    double Latitude { get; set; }
    double Longitude { get; set; }

    string AdminArea { get; set; }
    string CountryCode { get; set; }
    string CountryName { get; set; }
    string FeatureName { get; set; }
    string Locality { get; set; }
    string PostalCode { get; set; }
    string SubAdminArea { get; set; }
    string SubLocality { get; set; }
    string SubThoroughfare { get; set; }
    string Thoroughfare { get; set; }
}

Sensors API Magnetometer

Sensors API Magnetometer indicating the devices orientation relative to Earth's magnetic field.

API Level:

• iOS: CMMotionManager -> Create 1 Instance only
• Android: Sensor Listeners
• UWP: Windows.Device.Sensors

API:

bool IsListening {get;}
void Start(SensorSpeed speed, Action<MagnetometerData> handler);
void Stop();

struct MagnetometerData
{
   bool MagneticFieldX{ get; }
  bool MagneticFieldY{get;}
bool MagneticFieldZ{get;}
}

Sensors API Accelerometer

Sensors API Accelerometer to indicate the instantaneous acceleration of the device in three dimensional space.

API Level:

• iOS: CMMotionManager -> Create 1 Instance only
• Android: Sensor Listeners
• UWP: Windows.Device.Sensors

API:

bool IsListening {get;}
void Start(SensorSpeed speed, Action<AccelerometerData> handler);
void Stop();

struct AccelerometerData
{
   bool AccelerationX { get; }
  bool AccelerationY {get;}
bool AccelerationZ {get;}
}

Share API

Ability to Share text via a share sheet.

Things to consider:

• Title
• Chooser Title
• Message
• Link
• Activities to Exclude on iOS?

Each of these work a bit different so we should look at this.

Email API's

A simple API to send an email.

static class Email {
    static bool IsAttachmentSupported { get; }
    static bool IsHtmlMessageSupported { get; }

    // should throw a NotSupportedOnDeviceException if the device is not capable.
    Task ComposeAsync(EmailMessage message);

class EmailMessage {
    EmailMessage(string subject, string body, params string[] to);

    string Subject { get; set }
    string Body { get; set }
    bool IsMessageHtml { get; set }
    IList<string> To  { get; set; }
    IList<string> Bcc { get; set; }
    IList<string> Cc { get; set; }
    IList<EmailAttachment> Attachments { get; set; }

    // should throw a NotSupportedOnDeviceException if the device is not capable.
    void Attach(string attachmentName, string contentType, Stream stream);
    // should throw a NotSupportedOnDeviceException if the device is not capable.
    void Attach(string attachmentName, string contentType, string filename);
    // should throw a NotSupportedOnDeviceException if the device is not capable.
    void Attach(string attachmentName, string contentType, byte[] data);
}

class EmailAttachment {
    string Name { get; set; }
    string ContentType { get; set; }
    string FileName { get; set; }
    Stream Stream { get; set; }
}

For the discussion around exceptions, see #19

Permissions API's

Check and Request permissions.

Internally we need to ensure we have API’s for a couple of things:

• internal bool EnsurePermissionDeclared (string permission) checks if Info.plist on iOS, or AndroidManifest.xml, or x on UWP has the permission declared/defined and throws an exception with a meaningful error message including a link to documentation of how to ensure permissions are defined in the appropriate file for the given platform at runtime.

Permissions

public static class Permissions 
{
    public static Task<PermissionStatus> CheckPermissionAsync (string permission);
    public static Task<IDictionary<string, PermissionStatus>> CheckPermissionsAsync (params string[] permissions);

    public static Task<PermissionStatus> RequestPermissionAsync (string permission);
    public static Task<IDictionary<string, PermissionStatus>> RequestPermissionsAsync (params string[] permissions);
}

PermissionStatus (enum)

public enum PermissionStatus {
    Unknown,
    Denied,
    Disabled,
    Restricted,
    Granted,
}

Should Preferences support Nullable<T>?

This may be something that will be very useful.

@jamesmontemagno has done this in his plugin: https://github.com/jamesmontemagno/SettingsPlugin/blob/master/src/Plugin.Settings.Android/Settings.cs#L53-L60

mdoc Documentation

We want to document our API's with mdoc, and from that generate msxml docs to ship in the nupkg for providing intelligence information.

Sensors API Gyroscope

Sensors API Gyroscope to the instantaneous rotation around the device's three primary axes.

API Level:

• iOS: CMMotionManager -> Create 1 Instance only
• Android: Sensor Listeners
• UWP: Windows.Device.Sensors

API:

bool IsListening {get;}
void Start(SensorSpeed speed, Action<GyrometerData> handler);
void Stop();

struct GyrometerData
{
   bool AngularVelocityX { get; }
  bool AngularVelocityY {get;}
bool AngularVelocityX {get;}
}

Contribution Guidelines, PR & Issue Templates

We should have the following repository docs:

• Contributing document
• Issue Template
• Pull Request Template

Keep in mind, GitHub has conventions for these documents so that they appear appropriately to users in the Web UI (eg: When creating an issue, the issue is prepopulated with the template).

SMS API's

A simple API to send an SMS.

static class Sms {
    // whether or not the device can open a compose dialog
    static bool IsComposeSupported { get; }

    // whether or not the device can send in the background
    static bool IsSendSupported { get; }

    // open the compose window, throw if not supported
    static Task ComposeAsync(SmsMessage message);

    // send a message in the background, throw if not supported
    // this is supported only on Android and UWP
    static Task SendAsync(SmsMessage message);
}

class SmsMessage {
    SmsMessage(string body, string recipient);

    string Body { get; set; }
    string Recipient { get; set; }
}

For the discussion around exceptions, see #19

macOS support

(Enhancement)
Now that Xamarin.Mac is the same thing as Xamarin.iOS (xamarin-macios), supporting macOS should be low hanging fruit, right?

For example, with clipboard support.

MDocs creating docs for Support Libs

Bug report best practices: Submitting Issues

Description

Steps to Reproduce

1. Go to browser branch
2. run mdocs
3. all support libs will have docs generated

Device Capabilities

Would be nifty to abstract where we could into simple bools for devices capabilities:

bool HasTelephony { get; }
bool HasMicrophone { get; }
bool HasBluetooth { get; }
bool HasBluetoothLE { get; }
bool HasCamera { get; }
bool HasBiometric { get; }
bool HasIR { get; }
bool HasGPS { get; }
bool HasNFC { get; }
bool HasCompass { get; }
bool HasAccelerometer { get; }
bool HasBarometer { get; }
bool HasGyroscope { get; }
bool HasProximity { get; }
bool HasHeartrate { get; }
bool HasStepCounter { get; }
bool HasStepDetector { get; }

I think list would be a good start.