File Provider Extension: What It Is and How the iOS File Provider Works

What Is File Provider Extension in iOS

File Provider Extension is an app extension that adds new document sources to the Files app. A cloud service — Google Drive, Dropbox, OneDrive, or a corporate storage — can display its file structure directly in the system interface, without opening a separate app.

Users work with remote files just like with files saved on the device: browse folder contents, drag and drop documents, open them in any compatible app, and save changes back to the cloud. According to WWDC 2025, File Provider Extension supports up to 1000 simultaneous sync operations and adapts to network speed through dynamic priority management.

The extension runs in the background — iOS launches it when synchronization is needed and may force-terminate it when resources are low. All operations must be idempotent and support resumption from a checkpoint.

Architecture and File Synchronization Mechanism

File Provider Extension has a three-tier architecture: the Files.app system process, the provider extension, and the remote server. The system requests data from the extension, the extension translates requests into cloud service API calls, and returns results via NSFileProviderItem.

Incremental Synchronization

Instead of loading the full file structure on each update, the extension transfers only changed items. NSFileProviderManager provides methods for sending incremental updates — “file A added”, “file B modified”, “folder C deleted”. This drastically reduces traffic and speeds up change display.

According to Apple Engineering, incremental synchronization reduces data transfer volume by 60–80% compared to a full reload. It is recommended to use NSFileProviderSyncAnchor to mark the sync state and minimize duplicate requests.

On-Device Caching

File Provider Extension can cache files locally for offline access. When a file is opened, the system makes a request to the extension, and the extension decides whether to download the content from the server or return an already cached version. NSFileProviderItem indicates the caching level through the isDownloaded and isUploaded fields.

Apple recommends configuring caching policies based on file size: for images and documents — full caching, for videos — only previews, for archives — on user request.

NSFileProviderManager: Managing the File Provider

NSFileProviderManager is the central class through which the extension interacts with the system. It provides methods for notifying the system about changes, creating new items, managing downloads, and handling errors. Each NSFileProviderManager instance is tied to a specific domain.

Key Methods

signalEnumerator(for:) — notifies the system that folder contents have changed and need to be re-read. reimportItem(_:) — re-imports the specified item after a server-side change. registerURLSessionTask:forItemWithIdentifier: — associates a background download with a specific file for progress tracking.

Important limitation: NSFileProviderManager only works within the extension process. The main app cannot directly call its methods to manage the file structure — synchronization must be initiated by the extension or the system.

let manager = NSFileProviderManager.default()
manager.signalEnumerator(for: workingSet) { error in
    if let error = error {
        print("Signal failed: \(error)")
    }
}

Download Management

For background file downloads, NSFileProviderManager uses URLSession with a background configuration. The extension creates a download task and registers it with the manager, which associates it with the corresponding item. The system automatically tracks download progress and priorities based on user activity.

Implementing File Provider Extension

Creating a File Provider Extension starts with adding a new target in Xcode using the File Provider Extension template. Xcode automatically generates a class inheriting from NSFileProviderExtension and a minimal set of methods for working with items.

NSFileProviderItem and Metadata

Each item in the file structure — a file or folder — implements the NSFileProviderItem protocol. The protocol defines required fields: itemIdentifier, parentItemIdentifier, filename, typeIdentifier, and capabilities. Additionally, you can specify size, modification date, and download flags.

struct CloudItem: NSFileProviderItem {
    let itemIdentifier: NSFileProviderItemIdentifier
    let parentItemIdentifier: NSFileProviderItemIdentifier
    let filename: String
    let typeIdentifier: String
    let capabilities: NSFileProviderItemCapabilities
    let documentSize: NSNumber?
}

Handling Enumeration Requests

The enumerator(for:) method returns an object implementing NSFileProviderEnumerator, which provides the folder contents on system request. iOS may request enumeration for the root folder, subfolders, and a working set — the latter is used to display recent or favorite files.

Apple recommends using asynchronous enumeration methods with pagination via NSFileProviderPage to avoid loading thousands of items at once. Pages of 50–100 items are optimal for performance.

Domains and Multi-Account Architecture

NSFileProviderDomain is the mechanism for separating different accounts within a single extension. If a user has authorized multiple accounts in an app — personal and corporate Google Drive — each account creates a separate domain, which appears as a separate source in the Files app.

Each domain has a unique identifier, a display name, and a state. Users can temporarily disable domains or delete them without affecting other accounts. The system launches a separate extension process for each active domain, ensuring data isolation between accounts.

According to Apple, it is recommended not to create more than 10 domains per extension — an excessive number slows down the Files app launch and increases memory consumption. For services with a large number of accounts, it is worth aggregating them into a single domain with profile switching within the extension.

let domain = NSFileProviderDomain(
    identifier: "work",
    displayName: "Corporate Drive"
)
NSFileProviderManager.add(domain) { error in
    if let error = error {
        print("Failed to add domain: \(error)")
    }
}