Xamarin.Android: Adjusting legacy storage permissions for Android 13 deployments

Answer to the exact question

1. Automatic mapping: The current Xamarin.Android 12.x SDK does not translate READ_EXTERNAL_STORAGE to the new READ_MEDIA_IMAGES, READ_MEDIA_VIDEO, or READ_MEDIA_AUDIO permissions when you target API 33. The manifest is passed to AAPT unchanged, so the old permission is still requested and Android 13 will reject the request.

2. Recommended workflow:

• Remove READ_EXTERNAL_STORAGE (and WRITE_EXTERNAL_STORAGE) from AndroidManifest.xml.
• Add the specific media permissions you need, e.g.:

  <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
  <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
  <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
  

• Guard the permission request in code with Build.VERSION.SDK_INT >= 33.
• For devices below API 33, keep the legacy permission in the manifest (or use a uses-sdk element to split the manifest via Gradle’s productFlavors or manifestPlaceholders).
• Update file‑access logic to use MediaStore for media files. If you need arbitrary file access, consider migrating to app‑specific directories or request MANAGE_EXTERNAL_STORAGE with a Play Store justification.

3. Build‑time flag: No undocumented flag exists in Xamarin.Android to enable legacy‑to‑new permission mapping. The migration must be done manually, either by editing the manifest or by using a Gradle manifest merge strategy.

Why the change matters

Android 13 removes the legacy external‑storage model. Apps that still declare READ_EXTERNAL_STORAGE will see the permission dialog denied, and any attempt to open a media file will throw Permission denied: android.permission.READ_MEDIA_IMAGES in logcat. The only way to obtain media files is through the scoped media permissions or MANAGE_EXTERNAL_STORAGE (the latter requires Play Store approval).

Practical steps for Xamarin.Android projects

1. Update the manifest:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.example.app">
     <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="33" />
     <!-- Legacy for API < 33 -->
     <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:required="false" />
     <!-- New media permissions for API 33+ -->
     <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
     <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
   </manifest>
   

2. Code guard:

   if (Build.VERSION.SdkInt >= 33)
   {
       // Request READ_MEDIA_IMAGES, etc.
       ActivityCompat.RequestPermissions(this, new string[] { Android.Manifest.Permission.ReadMediaImages }, RequestCode);
   }
   else
   {
       // Request legacy READ_EXTERNAL_STORAGE
       ActivityCompat.RequestPermissions(this, new string[] { Android.Manifest.Permission.ReadExternalStorage }, RequestCode);
   }
   

3. File access: Replace Environment.GetExternalStoragePublicDirectory with MediaStore.Images.Media.GetContentUri or ContentResolver.OpenInputStream for media files.
4. Testing:
   • Run on a real Android 13 device or emulator.
   • Confirm that the permission dialog appears for the media permission.
   • Check logcat for any READ_EXTERNAL_STORAGE warnings.
   • Verify that media files can be read and that non‑media files are inaccessible unless you explicitly request MANAGE_EXTERNAL_STORAGE.

When to consider MANAGE_EXTERNAL_STORAGE

If your app still needs to read/write arbitrary files (e.g., PDFs, documents) outside the app’s sandbox, you must migrate to app‑specific directories or request MANAGE_EXTERNAL_STORAGE. This permission is highly scrutinized by Google Play, so provide a clear justification and privacy policy. Only use it as a last resort.

Unresolved diagnostic detail

Could you confirm whether your application accesses non‑media files (e.g., PDFs, documents) that would require broad storage access? The answer will determine if the migration can rely solely on media permissions or if MANAGE_EXTERNAL_STORAGE is necessary.

Verification checklist

• Target SDK set to 33 in AndroidManifest.xml and project properties.
• Legacy READ_EXTERNAL_STORAGE is present only for API < 33 (android:required="false").
• New media permissions added for API 33+.
• Permission requests guarded by Build.VERSION.SDK_INT checks.
• Media file access uses MediaStore APIs.
• Logcat shows no Permission denied: android.permission.READ_EXTERNAL_STORAGE errors after migration.