diff --git a/docs/platform-integration/essentials/email.md b/docs/platform-integration/essentials/email.md index 89d149a7b..e442a8b9f 100644 --- a/docs/platform-integration/essentials/email.md +++ b/docs/platform-integration/essentials/email.md @@ -1,21 +1,33 @@ --- title: "Email" -description: "The Email class in Microsoft.Maui.Essentials enables an application to open the default email application with a specified information including subject, body, and recipients (TO, CC, BCC)." -ms.date: 09/24/2020 +description: "Learn how to use the .MET MAUI Email class in Microsoft.Maui.Essentials to open the default email application. The subject, body, and recipients of email can be set." +ms.date: 08/12/2021 no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials"] --- # Email -The `Email` class enables an application to open the default email application with a specified information including subject, body, and recipients (TO, CC, BCC). +This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) Essentials `Email` class to open the default email app. When the email app is loaded, it can be set to create a new email with the specified recipients, subject, and body. -To access the **Email** functionality the following platform specific setup is required. +## Get started + +[!INCLUDE [get-started](includes/get-started.md)] + +[!INCLUDE [essentials-namespace](includes/essentials-namespace.md)] + +> [!WARNING] +> To use the email API on iOS, you must run it on a physical device. Otherwise, an exception is thrown. + +### Platform specific setup + +To access the email functionality the following platform specific setup is required. + # [Android](#tab/android) -If your project's Target Android version is set to **Android 11 (R API 30)** you must update your Android Manifest with queries that are used with the new [package visibility requirements](https://developer.android.com/preview/privacy/package-visibility). +If your project's _Target Android_ version is set to **Android 11 (R API 30)**, you must update your _Android Manifest_ with queries that are used with the [package visibility requirements](https://developer.android.com/preview/privacy/package-visibility). -Open the **AndroidManifest.xml** file under the **Properties** folder and add the following inside of the **manifest** node: +Open the _AndroidManifest.xml_ file under the **Properties** folder and add the following inside of the **manifest** node: ```xml @@ -28,7 +40,8 @@ Open the **AndroidManifest.xml** file under the **Properties** folder and add th # [iOS](#tab/ios) -In iOS 9 and greater, Apple enforces what schemes an application can query for. To query if email is a valid target the `mailto` scheme must be specified in the LSApplicationQueriesSchemes in your Info.plist file. + +In iOS 9 and greater, Apple enforces which schemes an application can query for. To query if **email** is a valid target, the `mailto` scheme must be specified for the `LSApplicationQueriesSchemes` scheme, in your _Info.plist_ file. ```xml LSApplicationQueriesSchemes @@ -39,16 +52,10 @@ In iOS 9 and greater, Apple enforces what schemes an application can query for. # [Windows](#tab/windows) -No platform differences. +No additional setup required. ----- - -## Get started - -[!INCLUDE [get-started](includes/get-started.md)] - -> [!TIP] -> To use the Email API on iOS you must run it on a physical device, else an exception will be thrown. + ## Using Email @@ -85,47 +92,56 @@ public class EmailTest } ``` -## File Attachments +## File attachments + +When creating the email provided to the email client, you can add file attachments. The API will automatically detect the file type (MIME), so you don't need to specify it. Some mail clients may restrict the types of files you send, or possibly prevent attachments all together. -This feature enables an app to email files in email clients on the device. Xamarin.Essentials will automatically detect the file type (MIME) and request the file to be added as an attachment. Every email client is different and may only support specific file extensions, or none at all. +Use the `EmailMessage.Attachments` collection to manage the files attached to an email. -Here is a sample of writing text to disk and adding it as an email attachment: +The following examples demonstrates adding arbitrary text to a file, then adding i tto the email. ```csharp var message = new EmailMessage { - Subject = "Hello", - Body = "World", + Subject = "To my friends", + Body = "Hello everyone!\r\n\r\nI've attached a list of my favorite memories.", }; -var fn = "Attachment.txt"; -var file = Path.Combine(FileSystem.CacheDirectory, fn); -File.WriteAllText(file, "Hello World"); +string fileName = "attachment.txt"; +string filePath = Path.Combine(FileSystem.CacheDirectory, fileName); -message.Attachments.Add(new EmailAttachment(file)); +File.WriteAllText(filePath, "Hello World"); + +message.Attachments.Add(new EmailAttachment(filePath)); await Email.ComposeAsync(message); ``` -## Platform differences +## Body type + +The body of an email message can specify either `Html` or `PlainText`. However, the platform and email client may or may not restrict the type of email you can send. + + # [Android](#tab/android) -Not all email clients for Android support `Html`, since there is no way to detect this we recommend using `PlainText` when sending emails. +Not all email clients for Android support `Html`, since there is no way to detect this, we recommend using `PlainText` when sending emails. # [iOS](#tab/ios) -No platform differences. +Both `Html` and `PlainText` are supported. # [Windows](#tab/windows) -Only supports `PlainText` as the `BodyFormat` attempting to send `Html` will throw a `FeatureNotSupportedException`. +Only supports `PlainText` as the `BodyFormat`. Attempting to send an `Html` email throws the exception: `FeatureNotSupportedException`. -Not all email clients support sending attachments. See [documentation](/windows/uwp/contacts-and-calendar/sending-email) for more information. +Not all email clients support sending attachments. For more information, see [Sending emails](/windows/uwp/contacts-and-calendar/sending-email). ----- + + ## API -- [Email source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Email) +- [Email source code](https://github.com/dotnet/maui/tree/main/src/Essentials/src/Email) diff --git a/docs/platform-integration/essentials/get-started.md b/docs/platform-integration/essentials/get-started.md index 20751b351..0d140913d 100644 --- a/docs/platform-integration/essentials/get-started.md +++ b/docs/platform-integration/essentials/get-started.md @@ -1,95 +1,84 @@ --- -title: "Get Started with Xamarin.Essentials" -description: "Get started with Xamarin.Essentials, which provides a single cross-platform API that works with any iOS, Android, or UWP application." -ms.date: 05/11/2020 +title: "Get Started with Essentials" +description: "Get started with Essentials in .NET MAUI. Essentials provides a single cross-platform API that your app can use to access device features, operating system functionality, and phone support, among other capabilities." +ms.date: 08/11/2021 no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials"] --- -# Get Started with Xamarin.Essentials +# Get started with .NET MAUI Essentials -Xamarin.Essentials provides 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. See the [platform & feature support guide](platform-feature-support.md) for more information on supported operating systems. +.NET Multi-platform App UI (.NET MAUI) Essentials provides a single cross-platform API that works with any iOS, Android, or UWP application. Essentials is accessed from cross-platform friendly code that is ignorant of the platform it's run on. Some APIs do require platform-specific configure or setup, but that's the exception rather than the rule. For more information about platform and operating system support, see [Platform Support](platform-feature-support.md). -## Installation +## Migrating from Xamarin.Forms -Xamarin.Essentials is available as a NuGet package and is included in every new project in Visual Studio. It can also be added to any existing projects using Visual Studio with the following steps. +Unlike Xamarin.Forms Essentials, .NET MAUI Essentials is included with .NET MAUI. You're no longer required to install a NuGet package or add reference to the Essentials library. -1. Download and install [Visual Studio](https://visualstudio.microsoft.com/) with the [Visual Studio tools for Xamarin](~/xamarin-forms/get-started/installation/index.md). +## Setup -2. Open an existing project, or create a new project using the Blank App template under **Visual Studio C#** (Android, iPhone & iPad, or Cross-Platform). +.NET MAUI Essentials requires setup on Android. iOS and Windows don't require any setup to enable access to Essentials. - > [!IMPORTANT] - > If adding to a UWP project ensure Build 16299 or higher is set in the project properties. + +# [Android](#tab/android) -3. Add the [**Xamarin.Essentials**](https://www.nuget.org/packages/Xamarin.Essentials/) NuGet package to each project: +.NET MAUI Essentials supports a minimum Android version of _4.4_, corresponding to _API level 19_, on the client device. But when compiling your project, the target Android version must be _9.0_ or _10.0_, corresponding to _API level 28_ and _API level 29_. - - # [Visual Studio](#tab/windows) +- Visual Studio for Windows - In the Solution Explorer panel, right click on the solution name and select **Manage NuGet Packages**. Search for **Xamarin.Essentials** and install the package into **ALL** projects including Android, iOS, UWP, and .NET Standard libraries. + These two versions are set in the Android project's properties. Right-click the project node in **Solution Explorer** and choose **Properties**, and navigate to the **Android Manifest** property page. - # [Visual Studio for Mac](#tab/macos) +- Visual Studio for Mac - In the Solution Explorer panel, right click on the project name and select **Add > Add NuGet Packages...**. Search for **Xamarin.Essentials** and install the package into **ALL** projects including Android, iOS, and .NET Standard libraries. + These two versions are set in the Project Options dialog for the Android project. Double-click the project node in the **Solution** pane, or right-click the project node and then select **Options**, then navigate to the **Android Application** tab. - ----- + +When compiling against Android 9.0, Xamarin.Essentials installs version 28.0.0.3 of the Xamarin.Android.Support libraries that it requires. Any other Xamarin.Android.Support libraries that your application requires should also be updated to version 28.0.0.3 using the NuGet package manager. All Xamarin.Android.Support libraries used by your application should be the same, and should be at least version 28.0.0.3. Refer to the [troubleshooting page](troubleshooting.md) if you have issues adding the Xamarin.Essentials NuGet or updating NuGets in your solution. -4. Add a reference to Xamarin.Essentials in any C# class to reference the APIs. +Starting with version 1.5.0 when compiling against Android 10.0, Xamarin.Essentials install AndroidX support libraries that it requires. Read through the [AndroidX documentation](../android/platform/androidx.md) if you have not made the transition yet. - ```csharp - using Xamarin.Essentials; - ``` + +### Configure the MainApplication or Activity + -5. Xamarin.Essentials requires platform-specific setup: +In the Android project's `MainApplication` or any `Activity` that is launched, Essentials must be initialized in the `OnCreate` method by calling the `Microsoft.Maui.Essentials.Platform.Init`method: - # [Android](#tab/android) - - Xamarin.Essentials supports a minimum Android version of 4.4, corresponding to API level 19, but the target Android version for compiling must be 9.0 or 10.0, corresponding to API level 28 and level 29. (In Visual Studio, these two versions are set in the Project Properties dialog for the Android project, in the Android Manifest tab. In Visual Studio for Mac, they're set in the Project Options dialog for the Android project, in the Android Application tab.) - - When compiling against Android 9.0, Xamarin.Essentials installs version 28.0.0.3 of the Xamarin.Android.Support libraries that it requires. Any other Xamarin.Android.Support libraries that your application requires should also be updated to version 28.0.0.3 using the NuGet package manager. All Xamarin.Android.Support libraries used by your application should be the same, and should be at least version 28.0.0.3. Refer to the [troubleshooting page](troubleshooting.md) if you have issues adding the Xamarin.Essentials NuGet or updating NuGets in your solution. - - Starting with version 1.5.0 when compiling against Android 10.0, Xamarin.Essentials install AndroidX support libraries that it requires. Read through the [AndroidX documentation](../android/platform/androidx.md) if you have not made the transition yet. +```csharp +public class MainActivity : MauiAppCompatActivity +{ + protected override void OnCreate(Bundle savedInstanceState) + { + base.OnCreate(savedInstanceState); + Microsoft.Maui.Essentials.Platform.Init(this, savedInstanceState); + } - In the Android project's `MainLauncher` or any `Activity` that is launched, Xamarin.Essentials must be initialized in the `OnCreate` method: + // ... Other code ... +} +``` - ```csharp - protected override void OnCreate(Bundle savedInstanceState) { - //... - base.OnCreate(savedInstanceState); - Xamarin.Essentials.Platform.Init(this, savedInstanceState); // add this line to your code, it may also be called: bundle - //... - ``` +### Configure the permissions - To handle runtime permissions on Android, Xamarin.Essentials must receive any `OnRequestPermissionsResult`. Add the following code to all `Activity` classes: +To handle runtime permissions on Android, permission requests must be passed on to Essentials by calling the `Microsoft.Maui.Essentials.Platform.OnRequestPermissionsResult` method. Add the following code to all `Activity` classes: - ```csharp - public override void OnRequestPermissionsResult(int requestCode, string[] permissions, Android.Content.PM.Permission[] grantResults) +```csharp +public class MainActivity : MauiAppCompatActivity +{ + public override void OnRequestPermissionsResult(int requestCode, string[] permissions, Permission[] grantResults) { - Xamarin.Essentials.Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults); + Microsoft.Maui.Essentials.Platform.OnRequestPermissionsResult(requestCode, permissions, grantResults); base.OnRequestPermissionsResult(requestCode, permissions, grantResults); } - ``` - - # [iOS](#tab/ios) - - No additional setup required. - - # [Windows](#tab/windows) - - No additional setup required. - - ----- - -6. Follow the [Xamarin.Essentials guides](index.md) that enable you to copy and paste code snippets for each feature. -## Xamarin.Essentials - Cross-Platform APIs for Mobile Apps (video) + // ... Other code ... +} +``` -> [!Video https://channel9.msdn.com/Shows/XamarinShow/Snack-Pack-XamarinEssentials-Cross-Platform-APIs-for-Mobile-Apps/player] +# [iOS](#tab/ios) -## Other Resources +No extra setup required. -We recommend developers new to Xamarin visit [getting started with Xamarin development](~/cross-platform/getting-started/index.md). +# [Windows](#tab/windows) -Visit the [Xamarin.Essentials GitHub Repository](https://github.com/xamarin/Essentials) to see the current source code, what is coming next, run samples, and clone the repository. Community contributions are welcome! +No extra setup required. -Browse through the [API documentation](xref:Xamarin.Essentials) for every feature of Xamarin.Essentials. +----- + diff --git a/docs/platform-integration/essentials/main-thread.md b/docs/platform-integration/essentials/main-thread.md index 5b29140e5..042e1043e 100644 --- a/docs/platform-integration/essentials/main-thread.md +++ b/docs/platform-integration/essentials/main-thread.md @@ -1,28 +1,26 @@ --- -title: "MainThread" -description: "The MainThread class allows applications to run code on the main execution thread." -ms.date: 08/20/2019 +title: Run code on the main UI thread +description: "In .NET MAUI, event handlers may be called on a secondary thread. The MainThread class allows an application to run code on the main UI thread. This article describes how to use the MainThread class." +ms.date: 08/12/2021 no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials"] --- # MainThread -The `MainThread` class allows applications to run code on the main thread of execution, and to determine if a particular block of code is currently running on the main thread. +This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) Essentials `MainThread` class to run code on the main UI thread. Most operating systems use a single-threading model for code involving the user interface. This model is necessary to properly serialize user-interface events, including keystrokes and touch input. This thread is often called the _main thread_, the _user-interface thread_, or the _UI thread_. The disadvantage of this model is that all code that accesses user interface elements must run on the application's main thread. -## Background +## When is it required -Most operating systems — including iOS, Android, and the Universal Windows Platform — use a single-threading model for code involving the user interface. This model is necessary to properly serialize user-interface events, including keystrokes and touch input. This thread is often called the _main thread_ or the _user-interface thread_ or the _UI thread_. The disadvantage of this model is that all code that accesses user interface elements must run on the application's main thread. - -Applications sometimes need to use events that call the event handler on a secondary thread of execution. (The Xamarin.Essentials classes [`Accelerometer`](sensors.md#accelerometer), [`Compass`](sensors.md#compass), [`Gyroscope`](sensors.md#gyroscope), [`Magnetometer`](sensors.md#magnetometer), and [`OrientationSensor`](sensors.md#orientation) all might return information on a secondary thread when used with faster speeds.) If the event handler needs to access user-interface elements, it must run that code on the main thread. The `MainThread` class allows the application to run this code on the main thread. +Applications sometimes need to use events that call the event handler on a secondary thread, such as the [`Accelerometer`](sensors.md#accelerometer) or [`Compass`](sensors.md#compass) sensors. All sensors might return information on a secondary thread when used with faster sensing speeds. If the event handler needs to access user-interface elements, it must invoke code on the main thread. ## Get started [!INCLUDE [get-started](includes/get-started.md)] -## Running Code on the Main Thread - [!INCLUDE [essentials-namespace](includes/essentials-namespace.md)] +## Run code on the UI thread + To run code on the main thread, call the static `MainThread.BeginInvokeOnMainThread` method. The argument is an [`Action`](xref:System.Action) object, which is simply a method with no arguments and no return value: ```csharp @@ -47,18 +45,9 @@ You can then run this method on the main thread by referencing it in the `BeginI MainThread.BeginInvokeOnMainThread(MyMainThreadCode); ``` -> [!NOTE] -> Xamarin.Forms has a method called -> [`Device.BeginInvokeOnMainThread(Action)`](/dotnet/api/xamarin.forms.device.begininvokeonmainthread) -> that does the same thing as `MainThread.BeginInvokeOnMainThread(Action)`. -> While you can use either method in a Xamarin.Forms app, consider whether -> or not the calling code has any other need for a dependency on -> Xamarin.Forms. If not, `MainThread.BeginInvokeOnMainThread(Action)` -> is likely a better option. +## Determine if invocation is required -## Determining if Code is Running on the Main Thread - -The `MainThread` class also allows an application to determine if a particular block of code is running on the main thread. The `IsMainThread` property returns `true` if the code calling the property is running on the main thread. A program can use this property to run different code for the main thread or a secondary thread: +With the `MainThread` class, you can determine if the current code is running on the main thread. The `MainThread.IsMainThread` property returns `true` if the code calling the property is running on the main thread, and `false` if it isn't. A program can use this property to run different code for the main thread or a secondary thread: ```csharp if (MainThread.IsMainThread) @@ -71,36 +60,33 @@ else } ``` -You might wonder if you should check if code is running on a secondary thread before calling `BeginInvokeOnMainThread`, for example, like this: +It's logical to assume that you need to determine if the code is running on the main thread before calling `BeginInvokeOnMainThread`. For example, the following code uses the `MainThread.IsMainThread` to detect if the `MyMainThreadCode` method should be called directly if the code is running on the main thread. If it isn't running on the main thread, the method is passed to `MainThread.BeginInvokeOnMainThread`: ```csharp if (MainThread.IsMainThread) -{ MyMainThreadCode(); -} + else -{ MainThread.BeginInvokeOnMainThread(MyMainThreadCode); -} ``` -You might suspect that this check might improve performance if the block of code is already running on the main thread. +This check isn't necessary. `BeginInvokeOnMainThread` itself tests if the current code is running on the main thread or not. If the code is running on the main thread, `BeginInvokeOnMainThread` just calls the provided method directly. If the code is running on a secondary thread, `BeginInvokeOnMainThread` invokes the provided method on the main thread. Therefore, if the code you run is the same, regardless of the main or secondary thread, simply call `BeginInvokeOnMainThread` without checking if it's required. There is negligible overhead in doing so. -_However, this check is not necessary._ The platform implementations of `BeginInvokeOnMainThread` themselves check if the call is made on the main thread. There is very little performance penalty if you call `BeginInvokeOnMainThread` when it's not really necessary. +The only reason you would need to check the `MainThread.IsMainThread` property is if you have branching logic that does something different based on the thread. -## Additional Methods +## Additional methods The `MainThread` class includes the following additional `static` methods that can be used to interact with user interface elements from backgrounds threads: -| Method | Arguments | Returns | Purpose | -|---|---|---|---| -| `InvokeOnMainThreadAsync` | `Func` | `Task` | Invokes a `Func` on the main thread, and waits for it to complete. | -| `InvokeOnMainThreadAsync` | `Action` | `Task` | Invokes an `Action` on the main thread, and waits for it to complete. | -| `InvokeOnMainThreadAsync`| `Func>` | `Task` | Invokes a `Func>` on the main thread, and waits for it to complete. | -| `InvokeOnMainThreadAsync` | `Func` | `Task` | Invokes a `Func` on the main thread, and waits for it to complete. | -| `GetMainThreadSynchronizationContextAsync` | | `Task` | Returns the `SynchronizationContext` for the main thread. | +| Method | Arguments | Returns | Purpose | +|------------------------------|-----------------|-----------|-----------------------------------------------------------------------------| +| `InvokeOnMainThreadAsync` | `Func` | `Task` | Invokes a `Func` on the main thread, and waits for it to complete. | +| `InvokeOnMainThreadAsync` | `Action` | `Task` | Invokes an `Action` on the main thread, and waits for it to complete. | +| `InvokeOnMainThreadAsync` | `Func>` | `Task` | Invokes a `Func>` on the main thread, and waits for it to complete. | +| `InvokeOnMainThreadAsync` | `Func` | `Task` | Invokes a `Func` on the main thread, and waits for it to complete. | +| `GetMainThreadSynchronizationContextAsync` | | `Task` | Returns the `SynchronizationContext` for the main thread. | ## API -- [MainThread source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/MainThread) +- [MainThread source code](https://github.com/dotnet/maui/tree/main/src/Essentials/src/MainThread) diff --git a/docs/platform-integration/essentials/platform-feature-support.md b/docs/platform-integration/essentials/platform-feature-support.md index b9eac2920..50c821fa6 100644 --- a/docs/platform-integration/essentials/platform-feature-support.md +++ b/docs/platform-integration/essentials/platform-feature-support.md @@ -1,54 +1,54 @@ --- -title: "Xamarin.Essentials Platform & Feature Support" -description: "Xamarin.Essentials provides 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." -ms.date: 08/20/2019 +title: "Essentials platform and feature support matrix" +description: "Learn about what features of .NET MAUI Essentials each platform supports." +ms.date: 08/11/2021 no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials"] --- -# Platform Support +# Platform support -Xamarin.Essentials supports the following platforms and operating systems: +This article describes which features of .NET Multi-platform App UI (.NET MAUI) Essentials are supported on the following platforms: -| Platform | Version | -| --- | --- | -| Android | 4.4 (API 19) or higher | -| iOS |10.0 or higher | -| Tizen | 4.0 or higher | -| tvOS | 10.0 or higher | -| watchOS | 4.0 or higher | -| UWP | 10.0.16299.0 or higher | -| macOS | 10.12.6 (Sierra) or higher | +| Platform | Version | +|----------|----------------------------| +| Android | 4.4 (API 19) or higher | +| iOS | 10.0 or higher | +| Tizen | 4.0 or higher | +| tvOS | 10.0 or higher | +| watchOS | 4.0 or higher | +| UWP | 10.0.16299.0 or higher | +| macOS | 10.12.6 (Sierra) or higher | > [!NOTE] > -> * Tizen is officially supported by the Samsung development team. -> * tvOS & watchOS have limited API coverage, please see the feature guide for more information. -> * macOS support is in preview. +> - **Tizen** is officially supported by the Samsung development team. +> - **tvOS** & **watchOS** have limited API coverage, please see the feature guide for more information. +> - **macOS** support is in preview. -## Feature Support +## Feature support -Xamarin.Essentials always tries to bring features to every platform, however sometimes there are limitations based on the device. Below is a guide of what features are supported on each platform. +The table below describes the .NET MAUI Essential features that are supported by each platform: Icon Guide: -* ✔️ - Full support -* ⚠️ - Limited support -* ❌ - Not supported +- ✔️ - Full support +- ⚠️ - Limited support +- ❌ - Not supported -| Feature | Android | iOS | UWP | watchOS | tvOS | Tizen | macOS | -|-------------------------------------------------------------------------------|:-------:|:---:|:---:|:-------:|:----:|:-----:|:-----:| -| [Accelerometer](sensors.md#accelerometer) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | +| Feature | Android | iOS | UWP | watchOS | tvOS | Tizen | macOS | +|-------------------------------------------------|:-------:|:---:|:---:|:-------:|:----:|:-----:|:-----:| +| [Accelerometer](sensors.md#accelerometer) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | | [App Actions](app-actions.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ❌ | ❌ | | [App Information](app-information.md) | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ✔️ | ✔️ | | [App Theme](app-theme.md) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ✔️ | -| [Barometer](sensors.md#barometer) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | +| [Barometer](sensors.md#barometer) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | | [Battery](battery.md) | ✔️ | ✔️ | ✔️ | ⚠️ | ❌ | ⚠️ | ✔️ | | [Clipboard](clipboard.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ❌ | ✔️ | | [Color Converters](color-converters.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| [Compass](sensors.md#compass) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ | +| [Compass](sensors.md#compass) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ | | [Connectivity](connectivity.md) | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ✔️ | ✔️ | | [Contacts](contacts.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ | -| [Detect Shake](sensors.md#shake) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | +| [Detect Shake](sensors.md#shake) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | | [Device Display Information](device-display.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ❌ | ✔️ | | [Device Information](device-information.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | | [Email](email.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | @@ -57,15 +57,15 @@ Icon Guide: | [Flashlight](flashlight.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ | | [Geocoding](geocoding.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | | [Geolocation](geolocation.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | -| [Gyroscope](sensors.md#gyroscope) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | +| [Gyroscope](sensors.md#gyroscope) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | | [Haptic Feedback](haptic-feedback.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | | [Launcher](launcher.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | -| [Magnetometer](sensors.md#magnetometer) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | +| [Magnetometer](sensors.md#magnetometer) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | | [MainThread](main-thread.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | | [Maps](maps.md) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ✔️ | | [Media Picker](media-picker.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ⚠️ | | [Open Browser](open-browser.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | -| [Orientation Sensor](sensors.md#orientation) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | +| [Orientation Sensor](sensors.md#orientation) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | | [Permissions](permissions.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | | [Phone Dialer](phone-dialer.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | | [Platform Extensions](platform-extensions.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | diff --git a/docs/platform-integration/essentials/sms.md b/docs/platform-integration/essentials/sms.md index 561a6b8b9..61cfe60ca 100644 --- a/docs/platform-integration/essentials/sms.md +++ b/docs/platform-integration/essentials/sms.md @@ -1,25 +1,30 @@ --- title: "SMS" -description: "The Sms class in Microsoft.Maui.Essentials enables an application to open the default SMS application with a specified message to send to a recipient." -ms.date: 09/24/2020 +description: "Learn how to use the .MET MAUI Sms class in Microsoft.Maui.Essentials to open the default SMS application. The text message can be preloaded with a message and recipient." +ms.date: 08/12/2021 no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials"] --- # SMS -The `Sms` class enables an application to open the default SMS application with a specified message to send to a recipient. +This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) Essentials `Sms` class to open the default SMS app and preload it with a message and recipient. ## Get started [!INCLUDE [get-started](includes/get-started.md)] -To access the **Sms** functionality the following platform specific setup is required. +[!INCLUDE [essentials-namespace](includes/essentials-namespace.md)] + +### Platform specific setup +To access the SMS functionality the following platform specific setup is required. + + # [Android](#tab/android) -If your project's Target Android version is set to **Android 11 (R API 30)** you must update your Android Manifest with queries that are used with the new [package visibility requirements](https://developer.android.com/preview/privacy/package-visibility). +If your project's _Target Android_ version is set to **Android 11 (R API 30)**, you must update your _Android Manifest_ with queries that are used with the [package visibility requirements](https://developer.android.com/preview/privacy/package-visibility). -Open the **AndroidManifest.xml** file under the **Properties** folder and add the following inside of the **manifest** node: +Open the _AndroidManifest.xml_ file under the **Properties** folder and add the following inside of the **manifest** node: ```xml @@ -36,24 +41,25 @@ No additional setup required. # [Windows](#tab/windows) -No platform differences. +No additional setup required. ----- + -## Using Sms +## Create a message [!INCLUDE [essentials-namespace](includes/essentials-namespace.md)] -The SMS functionality works by calling the `ComposeAsync` method an `SmsMessage` that contains the message's recipient and the body of the message, both of which are optional. +The SMS functionality works by creating a new `SmsMessage` object, and calling the `ComposeAsync` method. You can optionally include a message and zero or more recipients. ```csharp -public class SmsTest +public partial class SmsTest { public async Task SendSms(string messageText, string recipient) { try { - var message = new SmsMessage(messageText, new []{ recipient }); + var message = new SmsMessage(messageText, new[] { recipient }); await Sms.ComposeAsync(message); } catch (FeatureNotSupportedException ex) @@ -71,7 +77,7 @@ public class SmsTest Additionally, you can pass in multiple receipients to a `SmsMessage`: ```csharp -public class SmsTest +public partial class SmsTest { public async Task SendSms(string messageText, string[] recipients) { @@ -94,5 +100,5 @@ public class SmsTest ## API -- [Sms source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Sms) +- [Sms source code](https://github.com/dotnet/maui/tree/main/src/Essentials/src/Sms)