title | description | ms.date | no-loc | ||
---|---|---|---|---|---|
Contacts |
Learn how to use the .NET MAUI Contacts interface in the Microsoft.Maui.ApplicationModel.Communication namespace, which lets a pick a contact and retrieve information about it. |
02/02/2023 |
|
This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) xref:Microsoft.Maui.ApplicationModel.Communication.IContacts interface to select a contact and read information about it.
The default implementation of the IContacts
interface is available through the xref:Microsoft.Maui.ApplicationModel.Communication.Contacts.Default property. Both the IContacts
interface and Contacts
class are contained in the Microsoft.Maui.ApplicationModel.Communication
namespace.
Important
Picking a contact is unsupported on Windows.
Because of a namespace conflict, the Contacts
type must be fully qualified when targeting iOS or macOS: Microsoft.Maui.ApplicationModel.Communication.Contacts
. New projects automatically target these platforms, along with Android and Windows.
To write code that will compile for iOS and macOS, fully qualify the Contacts
type. Alternatively, provide a using
directive to map the Communication
namespace:
using Communication = Microsoft.Maui.ApplicationModel.Communication;
// Code that uses the namespace:
var contact = await Communication.Contacts.Default.PickContactAsync();
To access the Contacts functionality the following platform-specific setup is required.
The ReadContacts
permission is required and must be configured in the Android project. This can be added in the following ways:
-
Add the assembly-based permission:
Open the Platforms/Android/MainApplication.cs file and add the following assembly attribute after
using
directives:[assembly: UsesPermission(Android.Manifest.Permission.ReadContacts)]
- or -
-
Update the Android Manifest:
Open the Platforms/Android/AndroidManifest.xml file and add the following in the
manifest
node:<uses-permission android:name="android.permission.READ_CONTACTS" />
- or -
-
Update the Android Manifest in the manifest editor:
In Visual Studio double-click on the Platforms/Android/AndroidManifest.xml file to open the Android manifest editor. Then, under Required permissions check the READ_CONTACTS permission. This will automatically update the AndroidManifest.xml file.
In the Solution Explorer pane, right-click on the Platforms/iOS/Info.plist or Platforms/MacCatalyst/Info.plist file. Select Open With and then select the XML (Text) Editor item. Press the OK button. In the file, add the following key and value:
<key>NSContactsUsageDescription</key>
<string>This app needs access to contacts to pick a contact and get info.</string>
The <string>
element is the description specific to your app and is shown to the user.
Picking a contact is unsupported on Windows.
You can request the user to pick a contact by calling the xref:Microsoft.Maui.ApplicationModel.Communication.IContacts.PickContactAsync method. A contact dialog will appear on the device allowing the user to select a contact. If the user doesn't select a contact, null
is returned.
:::code language="csharp" source="../snippets/shared_1/CommsPage.xaml.cs" id="contact_select":::
The xref:Microsoft.Maui.ApplicationModel.Communication.IContacts.GetAllAsync%2A method returns a collection of contacts.
:::code language="csharp" source="../snippets/shared_1/CommsPage.xaml.cs" id="contact_all":::
This section describes the platform-specific differences with the contacts API.
- The
cancellationToken
parameter in the xref:Microsoft.Maui.ApplicationModel.Communication.IContacts.GetAllAsync%2A method isn't supported.
Important
Because of a namespace conflict, the Contacts
type must be fully qualified when targeting iOS or macOS: Microsoft.Maui.ApplicationModel.Communication.Contacts
.
- The
cancellationToken
parameter in the xref:Microsoft.Maui.ApplicationModel.Communication.IContacts.GetAllAsync%2A method isn't supported. - The iOS platform doesn't support the xref:Microsoft.Maui.ApplicationModel.Communication.Contact.DisplayName property natively, thus, the
DisplayName
value is constructed as "xref:Microsoft.Maui.ApplicationModel.Communication.Contact.GivenName xref:Microsoft.Maui.ApplicationModel.Communication.Contact.FamilyName".
Picking a contact is unsupported on Windows.