Shiny.Maui.ContactStore

Shiny.Maui.ContactStore

A cross-platform .NET MAUI library for accessing device contacts on Android and iOS. Provides full CRUD operations, LINQ query support, MAUI permission classes, and dependency injection integration.

Platforms

Setup

Install

dotnet add package Shiny.Maui.ContactStore

Registration

builder.Services.AddContactStore();

Platform Permissions

The library provides MAUI permission classes you can use with Permissions.RequestAsync:

• ContactReadPermission — read access to contacts
• ContactWritePermission — write access to contacts

Android — Add to AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />

iOS — Add to Info.plist:

<key>NSContactsUsageDescription</key>
<string>This app needs access to your contacts.</string>

iOS Notes & Relations Entitlement

Reading and writing the Note and Relationships properties on iOS requires the com.apple.developer.contacts.notes entitlement. The library automatically detects whether this entitlement is present at runtime. If absent, Note will return null and Relationships will be empty — no configuration or error handling needed on your part.

To enable notes and relations, add an Entitlements.plist with:

<key>com.apple.developer.contacts.notes</key>
<true/>

Note: This entitlement requires approval from Apple before it can be used in production apps.

Usage

Inject IContactStore into your class:

public class MyService(IContactStore contactStore)
{
}

Request Permission

var status = await Permissions.RequestAsync<ContactReadPermission>();
if (status != PermissionStatus.Granted)
{
    // handle denied
    return;
}

For write access:

var status = await Permissions.RequestAsync<ContactWritePermission>();

Get All Contacts

IReadOnlyList<Contact> contacts = await contactStore.GetAll();

Get Contact by ID

Contact? contact = await contactStore.GetById("some-id");

Query with LINQ

The library supports LINQ queries with native translation where possible and in-memory fallback for unsupported filters.

// Filter by name
var results = contactStore.Query()
    .Where(c => c.GivenName.Contains("John"))
    .ToList();

// Filter by phone number
var results = contactStore.Query()
    .Where(c => c.Phones.Any(p => p.Number.Contains("555")))
    .ToList();

// Filter by email
var results = contactStore.Query()
    .Where(c => c.Emails.Any(e => e.Address.Contains("@example.com")))
    .ToList();

// Combine filters
var results = contactStore.Query()
    .Where(c => c.GivenName.StartsWith("J") && c.FamilyName.Contains("Smith"))
    .ToList();

// Paging
var page = contactStore.Query()
    .Where(c => c.FamilyName.StartsWith("A"))
    .Skip(10)
    .Take(20)
    .ToList();

Supported query operations: Contains, StartsWith, EndsWith, Equals

Filterable properties: GivenName, FamilyName, MiddleName, NamePrefix, NameSuffix, Nickname, DisplayName, Note

Filterable collections: Phones (by Number), Emails (by Address)

Create a Contact

var contact = new Contact
{
    GivenName = "John",
    FamilyName = "Doe",
    Note = "Met at conference"
};
contact.Phones.Add(new ContactPhone("555-1234", PhoneType.Mobile));
contact.Emails.Add(new ContactEmail("[email protected]", EmailType.Work));

string id = await contactStore.Create(contact);

Update a Contact

var contact = await contactStore.GetById(id);
contact.GivenName = "Jane";
await contactStore.Update(contact);

Delete a Contact

await contactStore.Delete(contactId);

Models

Contact

Enums

PhoneType: Home, Mobile, Work, FaxWork, FaxHome, Pager, Other, Custom

EmailType: Home, Work, Other, Custom

AddressType: Home, Work, Other, Custom

ContactDateType: Birthday, Anniversary, Other, Custom

RelationshipType: Father, Mother, Parent, Brother, Sister, Child, Friend, Spouse, Partner, Assistant, Manager, Other, Custom