Skip to content

[essentials] port some more articles #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 13, 2021
Merged

[essentials] port some more articles #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 46 additions & 30 deletions docs/platform-integration/essentials/email.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<!-- markdownlint-disable MD025 -->
# [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
<queries>
Expand All @@ -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.
<!-- TODO: Verify the wording on this. Something was wrong in the original article and I don't know iOS well enough -->
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
<key>LSApplicationQueriesSchemes</key>
Expand All @@ -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.
<!-- markdownlint-enable MD025 -->

## Using Email

Expand Down Expand Up @@ -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.

<!-- markdownlint-disable MD025 -->
<!-- markdownlint-disable MD024 -->
# [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).

-----
<!-- markdownlint-enable MD024 -->
<!-- markdownlint-enable MD025 -->

## 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)
<!-- - [Email API documentation](xref:Microsoft.Maui.Essentials.Email)-->
111 changes: 50 additions & 61 deletions docs/platform-integration/essentials/get-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
<!-- markdownlint-disable MD025 -->
# [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_.

<!--markdownlint-disable MD023 -->
# [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.

-----
<!-- TODO: What is still valid in these two paragraphs? -->
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;
```
<!-- markdownlint-disable MD001 -->
### Configure the MainApplication or Activity
<!-- markdownlint-enable MD001 -->

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.
-----
<!-- markdownlint-enable MD025 -->
Loading