Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 42 ยท Platform Features

Runtime Permissions

Ask for camera, location and storage access correctly in .NET MAUI: manifest entries, Permissions.CheckStatusAsync, RequestAsync, rationale dialogs and denied states.

Phones protect the camera, microphone, location and contacts. Your app must declare what it wants and then ask the user at runtime. If you skip either step, the feature silently fails or the app crashes. This lesson shows the full flow in .NET MAUI and builds a small permission state machine you can run to understand the edge cases.

The Permissions API cannot run in a browser. The MAUI snippets are read-only. The runnable blocks are plain C# stand-ins that model the states and the decision logic.

Two steps: declare, then ask

Every permission needs an entry in the platform's configuration, and a runtime request.

Android (Platforms/Android/AndroidManifest.xml):

XML
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

iOS and Mac Catalyst (Platforms/iOS/Info.plist): a usage description string. The text is shown to the user in the system dialog, so write it for humans:

XML
<key>NSCameraUsageDescription</key>
<string>The camera is used to scan receipts.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location is used to show nearby stores.</string>

Windows (Package.appxmanifest): add the capability, for example webcam or location, under Capabilities.

If the iOS description is missing, the app is terminated the moment it asks.

The Permissions API

MAUI provides one class with generic methods. Each permission is a nested type such as Permissions.Camera, Permissions.LocationWhenInUse, Permissions.Microphone, Permissions.StorageRead, Permissions.Contacts, Permissions.Photos or Permissions.PostNotifications.

C#
public async Task<bool> EnsureCameraAsync()
{
    PermissionStatus status = await Permissions.CheckStatusAsync<Permissions.Camera>();

    if (status == PermissionStatus.Granted)
    {
        return true;
    }

    if (Permissions.ShouldShowRationale<Permissions.Camera>())
    {
        await Shell.Current.DisplayAlert(
            "Camera needed",
            "We use the camera to scan receipts.",
            "OK");
    }

    status = await Permissions.RequestAsync<Permissions.Camera>();
    return status == PermissionStatus.Granted;
}

PermissionStatus has these values:

Value Meaning
Unknown The system has no answer yet (common on iOS before the first prompt)
Denied The user refused (or can still be asked again on Android)
Disabled The feature is switched off on the device, for example location services
Granted You may proceed
Restricted A parental or policy control forbids it
Limited Partial access, such as selected photos on iOS 14+

The rules that trip people up

  • Ask in context. Request the camera when the user taps "Scan", not on app start. People grant permissions when they understand why.
  • The system may stop showing the prompt. On iOS you get one prompt. On Android, after repeated refusals the request returns Denied instantly. Your only option is to guide the user to the settings page: AppInfo.Current.ShowSettingsUI();.
  • Call permission methods on the UI thread. RequestAsync shows a system dialog. Use MainThread.InvokeOnMainThreadAsync if you are on a background thread.
  • Check again every time. The user can revoke a permission in system settings whenever they like.
  • Ask for the least you need. LocationWhenInUse is easier to justify than LocationAlways.
flowchart TD
    A["Feature requested"] --> B{"CheckStatusAsync"}
    B -- Granted --> G["Run the feature"]
    B -- Denied or Unknown --> C{"ShouldShowRationale?"}
    C -- yes --> D["Explain why"] --> E["RequestAsync"]
    C -- no --> E
    E -- Granted --> G
    E -- Denied --> F["Offer: open Settings"]
    B -- Disabled --> H["Tell the user to enable the feature"]

The decision flow every permission-guarded feature needs.

A reusable guard

Repeating that logic for every feature is tedious. Wrap it once:

C#
public static class PermissionGuard
{
    public static async Task<bool> EnsureAsync<TPermission>(string reason)
        where TPermission : Permissions.BasePermission, new()
    {
        var status = await Permissions.CheckStatusAsync<TPermission>();
        if (status == PermissionStatus.Granted) return true;

        if (Permissions.ShouldShowRationale<TPermission>())
        {
            await Shell.Current.DisplayAlert("Permission needed", reason, "OK");
        }

        status = await MainThread.InvokeOnMainThreadAsync(
            () => Permissions.RequestAsync<TPermission>());

        if (status != PermissionStatus.Granted)
        {
            bool open = await Shell.Current.DisplayAlert(
                "Permission denied",
                "You can enable it in Settings.",
                "Open Settings", "Not now");
            if (open) AppInfo.Current.ShowSettingsUI();
        }
        return status == PermissionStatus.Granted;
    }
}

Try it: simulate the permission flow

This stand-in has a fake operating system that remembers answers and refuses to prompt again after two denials, like Android.

C# Stand-in: a permission state machine

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Attempts 1 and 2 are refused, and the rationale shows after the first refusal. After two denials the fake system stops prompting, so attempts 3 and 4 fail immediately even though the queued third answer was "Allow": the user never gets the chance. That is exactly why you must explain the request before the second prompt, and why the Settings page is the way out. Change the queue to { true } to see the granted path.

Custom permissions and groups

Some features need several permissions. For example, a "find nearby" feature may need both location and Bluetooth. Create a class derived from Permissions.BasePermission (or Permissions.Location for permissions with platform-specific lists) and override RequiredPermissions per platform in Platforms/*. For most apps the built-in permission types are enough, so reach for this only when a native permission is missing from the list.

Handling the permission gracefully in the UI

Good apps degrade gracefully. When a permission is denied, show a clear message in the page instead of a blank area, and keep the rest of the app usable.

C# Stand-in: a view model that reflects permission state

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

In the real app the Message and ButtonText would be bindable properties, as covered in the MVVM chapter.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens on iOS if Info.plist lacks the camera usage description and the app requests the camera?

    iOS requires a usage description string; without it the system kills the app when it asks.
  2. 2. Which method tells you whether to show an explanation before asking again?

    ShouldShowRationale reports whether the platform thinks an explanation is appropriate, mainly on Android.
  3. 3. A user denied location twice on Android. What is the best next step?

    After repeated denials the system stops prompting, so the only way forward is the Settings page.
  4. 4. When should you request the camera permission?

    Asking in context improves the grant rate and respects the user.

Summary

  • Declare permissions in the manifest, Info.plist or Package.appxmanifest, then request at runtime.
  • CheckStatusAsync, RequestAsync and ShouldShowRationale are the three core calls.
  • Handle Denied, Disabled, Restricted and Limited, not only Granted.
  • Wrap the flow once in a guard and show a friendly fallback in the UI.

Next: Connectivity and Sensors