Edit

Contacts

  • Article

Browse sample. Browse the sample

This article describes how you can use the .NET Multi-platform App UI (.NET MAUI) IContacts interface to select a contact and read information about it.

The default implementation of the IContacts interface is available through the 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();

Get started

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.

Pick a contact

You can request the user to pick a contact by calling the 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.

private async void SelectContactButton_Clicked(object sender, EventArgs e)
{
    try
    {
        var contact = await Contacts.Default.PickContactAsync();

        if (contact == null)
            return;
        
        string id = contact.Id;
        string namePrefix = contact.NamePrefix;
        string givenName = contact.GivenName;
        string middleName = contact.MiddleName;
        string familyName = contact.FamilyName;
        string nameSuffix = contact.NameSuffix;
        string displayName = contact.DisplayName;
        List<ContactPhone> phones = contact.Phones; // List of phone numbers
        List<ContactEmail> emails = contact.Emails; // List of email addresses
    }
    catch (Exception ex)
    {
        // Most likely permission denied
    }
}

Get all contacts

The GetAllAsync method returns a collection of contacts.

public async IAsyncEnumerable<string> GetContactNames()
{
    var contacts = await Contacts.Default.GetAllAsync();

    // No contacts
    if (contacts == null)
        yield break;

    foreach (var contact in contacts)
        yield return contact.DisplayName;
}

Platform differences

This section describes the platform-specific differences with the contacts API.

  • The cancellationToken parameter in the GetAllAsync method isn't supported.