xamarin-macios/docs/required-reasons-bcl.md

Required Reasons API usage in .NET, Mono and the BCL

The tables provide lists of C# .NET APIs that call the Required Reasons APIs organized by category. These API usages are present in your app even if you do not explicitly call them. Therefore, you will be required to provide the API categories and reasons provided below in your apps PrivacyInfo.xcprivacy file. You may have to provide additional reason codes if you use the APIs directly, see Required Reasons APIs for more information on the reason codes.

Note: The following lists are verified only for .NET versions 8.0.0 and later.

File timestamp APIs

The following APIs either directly or indirectly access file timestamps and require reasons for use. Use the string NSPrivacyAccessedAPICategoryFileTimestamp as the value for the NSPrivacyAccessedAPIType key in your NSPrivacyAccessedAPITypes dictionary. Refer to File timestamp APIs for any additional relevant values to add to the NSPrivacyAccessedAPITypeReasons array.

.NET API	Internal Usages	CoreClr Usages	Mono Usages
System.Diagnostics.FileVersionInfo	Interop.Sys.LStat	SystemNative_LStat	g_file_test
System.IO.Compression.ZipFile.CreateFromDirectory	Interop.Sys.Stat	SystemNative_Stat	mono_file_map_size
System.IO.Directory.CreateDirectory(string)	Interop.Sys.FStat	SystemNative_FStat
System.IO.Directory.CreateDirectory(string, UnixFileMode)	System.Runtime.Loader.AssemblyLoadContext.ResolveSatelliteAssembly
System.IO.Directory.Delete(string)
System.IO.Directory.Exists(string?)
System.IO.Directory.GetCreationTime(string)
System.IO.Directory.GetCreationTimeUtc(string)
System.IO.Directory.GetLastAccessTime(string)
System.IO.Directory.GetLastAccessTimeUtc(string)
System.IO.Directory.GetLastWriteTime(string)
System.IO.Directory.GetLastWriteTimeUtc(string)
System.IO.Directory.Move(string, string)
System.IO.DirectoryInfo.Delete(string?)
System.IO.DirectoryInfo.MoveTo(string)
System.IO.Enumeration.FileSystemEntry.Attributes
System.IO.Enumeration.FileSystemEntry.CreationTime
System.IO.Enumeration.FileSystemEntry.CreationTimeUtc
System.IO.Enumeration.FileSystemEntry.IsHidden
System.IO.Enumeration.FileSystemEntry.LastAccessTime
System.IO.Enumeration.FileSystemEntry.LastAccessTimeUtc
System.IO.Enumeration.FileSystemEntry.LastWriteTime
System.IO.Enumeration.FileSystemEntry.LastWriteTimeUtc
System.IO.Enumeration.FileSystemEntry.Length
System.IO.Enumeration.FileSystemEntry.ToFileSystemInfo()
System.IO.File.Copy(string, string)
System.IO.File.Copy(string, string, boolean)
System.IO.File.Delete(string)
System.IO.File.Exists(string?)
System.IO.File.GetAttributes(SafeFileHandle)
System.IO.File.GetAttributes(string)
System.IO.File.GetCreationTime(SafeFileHandle)
System.IO.File.GetCreationTime(string)
System.IO.File.GetCreationTimeUtc(SafeFileHandle)
System.IO.File.GetCreationTimeUtc(string)
System.IO.File.GetLastAccessTime(SafeFileHandle)
System.IO.File.GetLastAccessTime(string)
System.IO.File.GetLastAccessTimeUtc(SafeFileHandle)
System.IO.File.GetLastAccessTimeUtc(string)
System.IO.File.GetLastWriteTime(SafeFileHandle)
System.IO.File.GetLastWriteTime(string)
System.IO.File.GetLastWriteTimeUtc(SafeFileHandle)
System.IO.File.GetLastWriteTimeUtc(string)
System.IO.File.GetUnixFileMode(SafeFileHandle)
System.IO.File.GetUnixFileMode(string)
System.IO.File.Move(string, string)
System.IO.File.Move(string, string, boolean)
System.IO.File.OpenHandle(string, FileMode, FileAccess, FileShare, FileOptions, long)
System.IO.File.Replace(string, string, string)
System.IO.File.Replace(string, string, string, boolean)
System.IO.File.ReadAllBytes(string)
System.IO.File.ReadAllBytesAsync(string, CancellationToken)
System.IO.FileInfo.Delete()
System.IO.FileInfo.MoveTo(string, string)
System.IO.FileInfo.MoveTo(string, string, boolean)
System.IO.FileInfo.Replace(string, string)
System.IO.FileInfo.Replace(string, string, boolean)
System.IO.FileSystemInfo.Attributes
System.IO.FileSystemInfo.CreationTime
System.IO.FileSystemInfo.CreationTimeUtc
System.IO.FileSystemInfo.LastAccessTime
System.IO.FileSystemInfo.LastAccessTimeUtc
System.IO.FileSystemInfo.LastWriteTime
System.IO.FileSystemInfo.LastWriteTimeUtc
System.IO.FileSystemInfo.Length
System.IO.FileSystemInfo.Refresh()
System.IO.FileSystemInfo.UnixFileMode
System.IO.FileSystemWatcher
System.IO.IsolatedStorage.IsolatedStorageFile.MoveDirectory(string, string)
System.IO.IsolatedStorage.IsolatedStorageFile.MoveFile(string, string)
System.IO.MemoryMappedFiles.MemoryMappedFile.CreateFromFile(string)
System.IO.MemoryMappedFiles.MemoryMappedFile.CreateFromFile(string, FileMode)
System.IO.MemoryMappedFiles.MemoryMappedFile.CreateFromFile(string, FileMode, string?)
System.IO.MemoryMappedFiles.MemoryMappedFile.CreateFromFile(string, FileMode, string?, long)
System.IO.MemoryMappedFiles.MemoryMappedFile.CreateFromFile(string, FileMode, string?, long, MemoryMappedFileAccess)
System.IO.Path.Exists(string?)
System.IO.Pipes.AnonymousPipeClientStream
System.IO.Pipes.AnonymousPipeServerStream
System.IO.Pipes.NamedPipeClientStream
System.IO.Pipes.NamedPipeServerStream
System.IO.RandomAccess.GetLength(SafeFileHandle)
System.Formats.Tar.TarWriter.WriteEntry(TarEntry)
System.Formats.Tar.TarWriter.WriteEntry(string, string)
System.Formats.Tar.TarWriter.WriteEntryAsync(TarEntry, CancellationToken)
System.Formats.Tar.TarWriter.WriteEntryAsync(string, string, CancellationToken)
System.Net.Sockets.Socket.SendPacketsAsync(SocketAsyncEventArgs)
System.TimeZoneInfo.Local

For example, if you use any of the APIs listed above, your PrivacyInfo.xcprivacy would contain the dict element in the NSPrivacyAccessedAPITypes key's array as shown below:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>C617.1</string>
            </array>
        </dict>
    </array>
</dict>
</plist>

Additional reason codes from File timestamp APIs can be provided in the array following the NSPrivacyAccessedAPITypeReasons key.

System boot time APIs

The following APIs either directly or indirectly access the system boot time and require reasons for use. Use the string NSPrivacyAccessedAPICategorySystemBootTime as the value for the NSPrivacyAccessedAPIType key in your NSPrivacyAccessedAPITypes dictionary. If you only access the system boot time from the list of APIs below, then use the 35F9.1 value in the NSPrivacyAccessedAPITypeReasons array.

.NET API	Internal Usages	CoreClr Usages	Mono Usages
System.Environment.TickCount			mono_msec_boottime
System.Environment.TickCount64			mono_domain_finalize
			mono_join_uninterrupted
			mono_msec_ticks
			mono_100ns_ticks
			threads_wait_pending_joinable_threads
			current_time

For example, if you use any of the APIs listed above, your PrivacyInfo.xcprivacy would contain the dict element in the NSPrivacyAccessedAPITypes key's array as shown below:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategorySystemBootTime</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>35F9.1</string>
            </array>
        </dict>
    </array>
</dict>
</plist>

Disk space APIs

The following APIs either directly or indirectly access the available disk space and require reasons for use. Use the string NSPrivacyAccessedAPICategoryDiskSpace as the value for the NSPrivacyAccessedAPIType key in your NSPrivacyAccessedAPITypes dictionary. If you access the available disk space from the list of APIs below, then use Disk space APIs to determine the correct values to place in the NSPrivacyAccessedAPITypeReasons array.

.NET API	Internal Usages	CoreClr Usages	Mono Usages
System.IO.DriveInfo.AvailableFreeSpace	Interop.Sys.TryGetFileSystemType	SystemNative_GetFileSystemType
System.IO.DriveInfo.DriveFormat	Interop.Sys.GetSpaceInfoForMountPoint	SystemNative_GetSpaceInfoForMountPoint
System.IO.DriveInfo.DriveType	Interop.Sys.GetFormatInfoForMountPoint	SystemNative_GetFormatInfoForMountPoint
System.IO.DriveInfo.TotalFreeSpace
System.IO.DriveInfo.TotalSize
System.IO.File.Copy(string, string)
System.IO.File.Copy(string, string, boolean)
System.IO.File.OpenHandle(string, FileMode, FileAccess, FileShare, FileOptions, long)
System.IO.MemoryMappedFiles.MemoryMappedFile.CreateFromFile(string)
System.IO.MemoryMappedFiles.MemoryMappedFile.CreateFromFile(string, FileMode)
System.IO.MemoryMappedFiles.MemoryMappedFile.CreateFromFile(string, FileMode, string?)
System.IO.MemoryMappedFiles.MemoryMappedFile.CreateFromFile(string, FileMode, string?, long)
System.IO.MemoryMappedFiles.MemoryMappedFile.CreateFromFile(string, FileMode, string?, long, MemoryMappedFileAccess)
System.TimeZoneInfo.Local
System.Net.Sockets.Socket.SendPacketsAsync(SocketAsyncEventArgs)

For example, if you use any of the APIs listed above, your PrivacyInfo.xcprivacy would contain the dict element in the NSPrivacyAccessedAPITypes key's array as shown below:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategoryDiskSpace</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>E174.1</string>
            </array>
        </dict>
    </array>
</dict>
</plist>

Reason codes from Disk space APIs can be provided in the array following the NSPrivacyAccessedAPITypeReasons key.