Autorisations d’accès aux fichiers

  • Article

Les applications de plateforme Windows universelle (UWP) peuvent accéder à certains emplacements de systèmes de fichiers par défaut. Les applications peuvent également accéder à des emplacements supplémentaires par le biais du sélecteur de fichiers, ou en déclarant des fonctionnalités.

Emplacements accessibles aux applications UWP

Lorsque vous créez une application, vous pouvez accéder par défaut aux emplacements suivants du système de fichiers :

Répertoire d’installation de l’application

Dossier dans lequel votre application est installée sur le système de l’utilisateur.

Il existe deux manières principales d’accéder à des fichiers et des dossiers dans le répertoire d’installation de votre application :

  1. Vous pouvez récupérer une classe StorageFolder qui représente le répertoire d’installation de votre application, comme suit :

    Windows.Storage.StorageFolder installedLocation = Windows.ApplicationModel.Package.Current.InstalledLocation;

    var installDirectory = Windows.ApplicationModel.Package.current.installedLocation;

    #include <winrt/Windows.Storage.h>
...
Windows::Storage::StorageFolder installedLocation{ Windows::ApplicationModel::Package::Current().InstalledLocation() };

    Windows::Storage::StorageFolder^ installedLocation = Windows::ApplicationModel::Package::Current->InstalledLocation;

    Vous pouvez accéder aux fichiers et dossiers du répertoire à l’aide des méthodes StorageFolder. Dans l’exemple, cette classe StorageFolder est stockée dans la variable installDirectory. Pour plus d’informations sur l’utilisation de votre package d’application et du répertoire d’installation, consultez l’exemple d’informations de package d’application sur GitHub.

  2. Vous pouvez récupérer un fichier directement à partir du répertoire d’installation de votre application en utilisant un URI d’application, comme suit :

    using Windows.Storage;            
StorageFile file = await StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appx:///file.txt"));

    Windows.Storage.StorageFile.getFileFromApplicationUriAsync("ms-appx:///file.txt").done(
    function(file) {
        // Process file
    }
);

    Windows::Foundation::IAsyncAction ExampleCoroutineAsync()
{
    Windows::Storage::StorageFile file{
        co_await Windows::Storage::StorageFile::GetFileFromApplicationUriAsync(Windows::Foundation::Uri{L"ms-appx:///file.txt"})
    };
    // Process file
}

    auto getFileTask = create_task(StorageFile::GetFileFromApplicationUriAsync(ref new Uri("ms-appx:///file.txt")));
getFileTask.then([](StorageFile^ file) 
{
    // Process file
});

    Une fois la méthode GetFileFromApplicationUriAsync exécutée, elle renvoie une classe StorageFile qui représente le fichier file.txt dans le répertoire d’installation de l’application (file dans cet exemple).

    Le préfixe « ms-appx:/// » de l’URI fait référence au répertoire d’installation de l’application. Pour en savoir plus sur l’utilisation des URI d’application, voir Comment utiliser des URI pour référencer du contenu.

En outre, contrairement à d’autres emplacements, vous pouvez également accéder à des fichiers dans le répertoire d’installation de votre application à l’aide de certaines API Win32 et COM pour les applications de plateforme Windows universelle (UWP) et de certaines fonctions de la bibliothèque C/C++ standard à partir de Microsoft Visual Studio.

Le répertoire d’installation de l’application est un emplacement en lecture seule. Vous ne pouvez pas accéder à ce répertoire d’installation par le biais du sélecteur de fichiers.

Accéder aux emplacements des données d’application

Les dossiers dans lesquels votre application peut stocker des données. Ces dossiers (local, roaming et temporary) sont créés lors de l’installation de votre application.

Il existe deux manières principales d’accéder à des fichiers et des dossiers dans les emplacements des données de votre application :

  1. Utilisez les propriétés ApplicationData pour récupérer un dossier de données de l’application.

    Par exemple, vous pouvez utiliser ApplicationData.LocalFolder pour récupérer une classe StorageFolder qui représente le dossier local de votre application, comme suit :

    using Windows.Storage;
StorageFolder localFolder = ApplicationData.Current.LocalFolder;

    var localFolder = Windows.Storage.ApplicationData.current.localFolder;

    Windows::Storage::StorageFolder storageFolder{
    Windows::Storage::ApplicationData::Current().LocalFolder()
};

    using namespace Windows::Storage;
StorageFolder^ storageFolder = ApplicationData::Current->LocalFolder;

    Si vous souhaitez accéder au dossier roaming ou temporary de votre application, utilisez la propriété RoamingFolder ou TemporaryFolder à la place.

    Une fois que vous avez récupéré une classe StorageFolder qui représente un emplacement des données de l’application, vous pouvez accéder aux fichiers et dossiers situés dans cet emplacement en utilisant les méthodes StorageFolder. Dans cet exemple, ces objets StorageFolder sont stockés dans la variable localFolder. Pour plus d’informations sur l’utilisation des emplacements de données de l’application, consultez la page Classe ApplicationData, puis téléchargez l’exemple de données d’application à partir de GitHub.

  2. Par exemple, vous pouvez récupérer un fichier directement à partir du dossier local de votre application en utilisant un URI d’application, comme suit :

    using Windows.Storage;
StorageFile file = await StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appdata:///local/file.txt"));

    Windows.Storage.StorageFile.getFileFromApplicationUriAsync("ms-appdata:///local/file.txt").done(
    function(file) {
        // Process file
    }
);

    Windows::Storage::StorageFile file{
    co_await Windows::Storage::StorageFile::GetFileFromApplicationUriAsync(Windows::Foundation::Uri{ L"ms-appdata:///local/file.txt" })
};
// Process file

    using Windows::Storage;
auto getFileTask = create_task(StorageFile::GetFileFromApplicationUriAsync(ref new Uri("ms-appdata:///local/file.txt")));
getFileTask.then([](StorageFile^ file) 
{
    // Process file
});

    Une fois la méthode GetFileFromApplicationUriAsync exécutée, elle renvoie une classe StorageFile qui représente le fichier file.txt dans le dossier local de l’application (file dans cet exemple).

    Le préfixe « ms-appdata:///local/ » de l’URI fait référence au dossier local de l’application. Pour accéder à des fichiers dans les dossiers roaming ou temporary, utilisez « ms-appdata:///roaming/ » ou « ms-appdata:///temporary/ » à la place. Pour en savoir plus sur l’utilisation des URI d’application, voir Comment charger des ressources de fichiers.

En outre, contrairement à d’autres emplacements, vous pouvez également accéder à des fichiers dans les emplacements de données de votre application à l’aide de certaines API Win32 et COM pour les applications UWP et de certaines fonctions de la bibliothèque C/C++ standard à partir de Microsoft Visual Studio.

Vous ne pouvez pas accéder aux dossiers local, roaming ni temporary par le biais du sélecteur de fichiers.

Accéder aux appareils amovibles

De plus, votre application peut accéder par défaut à certains fichiers sur les périphériques connectés. Cela est une option si votre application utilise l’extension de lecture automatique pour se lancer automatiquement lorsque l’utilisateur connecte un appareil, tel qu’un appareil photo ou une clé USB, à son système. Les fichiers auxquels votre application peut accéder sont limités aux types de fichiers spécifiques qui sont spécifiés par le biais de déclarations d’associations de types de fichiers dans le manifeste de votre application.

Bien entendu, vous pouvez également accéder à des fichiers et dossiers sur un périphérique amovible en appelant le sélecteur de fichiers (en utilisant FileOpenPicker et FolderPicker) et en laissant l’utilisateur sélectionner les fichiers et dossiers auxquels votre application pourra accéder. Découvrez comment utiliser le sélecteur de fichiers dans Ouvrir des fichiers et dossiers à l’aide d’un sélecteur.

Notes

Pour en savoir plus sur l’accès à une carte mémoire Secure Digital ou à d’autres appareils amovibles, consultez l’article Accéder à la carte SD.

Dossier Téléchargements de l’utilisateur

Dossier dans lequel les fichiers téléchargés sont enregistrés par défaut.

Par défaut, votre application peut seulement accéder aux fichiers et dossiers situés dans le dossier Téléchargements de l’utilisateur que votre application a créé. Toutefois, vous pouvez accéder aux fichiers et dossiers situés dans le dossier Téléchargements de l’utilisateur en appelant un sélecteur de fichiers (FileOpenPicker ou FolderPicker) afin que les utilisateurs puissent parcourir et sélectionner les fichiers ou les dossiers auxquels votre application pourra accéder.

  • Vous pouvez créer un fichier dans le dossier Téléchargements de l’utilisateur comme suit :

    using Windows.Storage;
StorageFile newFile = await DownloadsFolder.CreateFileAsync("file.txt");

    Windows.Storage.DownloadsFolder.createFileAsync("file.txt").done(
    function(newFile) {
        // Process file
    }
);

    Windows::Storage::StorageFile newFile{
    co_await Windows::Storage::DownloadsFolder::CreateFileAsync(L"file.txt")
};
// Process file

    using Windows::Storage;
auto createFileTask = create_task(DownloadsFolder::CreateFileAsync(L"file.txt"));
createFileTask.then([](StorageFile^ newFile)
{
    // Process file
});

    DownloadsFolder.CreateFileAsync est surchargé afin que vous puissiez spécifier ce que le système doit faire si le dossier Téléchargements contient déjà un fichier du même nom. Une fois ces méthodes exécutées, elles renvoient une classe StorageFile qui représente le fichier qui a été créé. Ce fichier est appelé newFile dans cet exemple.

  • Vous pouvez créer un sous-dossier dans le dossier Téléchargements de l’utilisateur comme suit :

    using Windows.Storage;
StorageFolder newFolder = await DownloadsFolder.CreateFolderAsync("New Folder");

    Windows.Storage.DownloadsFolder.createFolderAsync("New Folder").done(
    function(newFolder) {
        // Process folder
    }
);

    Windows::Storage::StorageFolder newFolder{
    co_await Windows::Storage::DownloadsFolder::CreateFolderAsync(L"New Folder")
};
// Process folder

    using Windows::Storage;
auto createFolderTask = create_task(DownloadsFolder::CreateFolderAsync(L"New Folder"));
createFolderTask.then([](StorageFolder^ newFolder)
{
    // Process folder
});

    DownloadsFolder.CreateFolderAsync est surchargé afin que vous puissiez spécifier ce que le système doit faire si le dossier Téléchargements contient déjà un sous-dossier du même nom. Une fois ces méthodes exécutées, elles renvoient une classe StorageFolder qui représente le sous-dossier qui a été créé. Ce fichier est appelé newFolder dans cet exemple.

Accès à des emplacements supplémentaires

Outre les emplacements par défaut, une application peut accéder à des fichiers et dossiers supplémentaires en déclarant des fonctionnalités dans le manifeste de l’application, ou en appelant un sélecteur de fichiers pour permettre à l’utilisateur de sélectionner les fichiers et les dossiers auxquels l’application peut accéder.

Les applications qui déclarent l’extension AppExecutionAlias disposent des autorisations de systèmes de fichiers à partir du répertoire d’où elles sont lancées dans la fenêtre de console et aux niveaux inférieurs.

Conserver l’accès aux fichiers et aux dossiers

Lorsque votre application récupère un fichier ou un dossier à l’aide d’un sélecteur, d’une activation de fichier, d’une opération de glisser-déposer, etc., elle a uniquement accès à ce fichier ou à ce dossier pendant l’opération de récupération. Si vous souhaitez accéder automatiquement à ce fichier ou à ce dossier la prochaine fois, vous pouvez l’ajouter à la FutureAccessList pour permettre à votre application d’y accéder. Vous pouvez également utiliser la MostRecentlyUsedList pour gérer facilement la liste des fichiers récemment utilisés.

Fonctionnalités d’accès aux autres emplacements

Le tableau qui suit dresse une liste d’emplacements supplémentaires auxquels vous pouvez accéder en déclarant une ou plusieurs fonctionnalités, et en utilisant l’API Windows.Storage associée.

Emplacement Fonctionnalité API Windows.Storage
Tous les fichiers auxquels l’utilisateur a accès. Par exemple : documents, images, photos, téléchargements, bureau, OneDrive, etc. broadFileSystemAccess

Il s’agit d’une fonctionnalité restreinte. L’accès est configurable dans Paramètres>Confidentialité>Système de fichiers. Étant donné que les utilisateurs peuvent accorder ou refuser leur autorisation à tout moment dans Paramètres, vous devez vous assurer que votre application résiste à ces modifications. Si vous constatez que votre application ne dispose d’aucun accès, vous pouvez inviter l’utilisateur à modifier le paramètre en fournissant un lien vers l’article Accès au système de fichiers Windows 10 et confidentialité. L’utilisateur doit fermer l’application, activer/désactiver le paramètre et redémarrer l’application. S’il active/désactive le paramètre pendant l’exécution de l’application, la plateforme interrompt votre application de sorte que vous puissiez enregistrer l’état, puis quitter l’application afin d’appliquer le nouveau paramètre. Dans la mise à jour d’avril 2018, la valeur par défaut pour l’autorisation est Activé. Dans la mise à jour d’octobre 2018, la valeur par défaut est Désactivé.

Si vous soumettez une application au Store qui déclare cette fonctionnalité, vous devez fournir des descriptions supplémentaires de la raison pour laquelle votre application a besoin de cette fonctionnalité, et comment elle a l’intention de l’utiliser.

Cette fonctionnalité concerne les API dans l’espace de noms Windows.Storage. Consultez la section Exemple à la fin de cet article pour découvrir comment activer cette fonctionnalité dans votre application.

Remarque : Cette fonctionnalité n’est pas prise en charge sur Xbox.		 n/a
Documents documentsLibrary

Remarque : vous devez ajouter des associations de types de fichiers dans le manifeste de l’application pour déclarer les types de fichiers spécifiques auxquels votre application pourra accéder dans cet emplacement.

Utilisez cette fonctionnalité si votre application :
- facilite l’accès hors connexion interplateforme à du contenu OneDrive spécifique à l’aide d’URL ou d’ID de ressource OneDrive valides ;
- Enregistre automatiquement les fichiers ouverts sur le OneDrive de l’utilisateur en mode hors connexion		 KnownFolders.DocumentsLibrary
Musique musicLibrary
Voir également Fichiers et dossiers dans les bibliothèques de musique, d’images et de vidéos.		 KnownFolders.MusicLibrary
Images picturesLibrary
Voir également Fichiers et dossiers dans les bibliothèques de musique, d’images et de vidéos.		 KnownFolders.PicturesLibrary
Vidéos videosLibrary
Voir également Fichiers et dossiers dans les bibliothèques de musique, d’images et de vidéos.		 KnownFolders.VideosLibrary
Périphériques amovibles removableStorage

Remarque : vous devez ajouter des associations de types de fichiers dans le manifeste de l’application pour déclarer les types de fichiers spécifiques auxquels votre application pourra accéder dans cet emplacement.

Voir également Accéder à la carte SD.		 KnownFolders.RemovableDevices
Bibliothèques du groupe résidentiel Au moins une des fonctionnalités suivantes est requise.
- musicLibrary
- picturesLibrary
- videosLibrary		 KnownFolders.HomeGroup
Appareils de serveur multimédia (DLNA) Au moins une des fonctionnalités suivantes est requise.
- musicLibrary
- picturesLibrary
- videosLibrary		 KnownFolders.MediaServerDevices
Dossiers UNC (Universal Naming Convention) Une combinaison des fonctionnalités suivantes est requise.

La capacité des réseaux domestiques et professionnels :
- privateNetworkClientServer

Et au moins une capacité Internet et réseaux publics :
- internetClient
- internetClientServer

Et, le cas échéant, la fonctionnalité des informations d’identification de domaine :
- enterpriseAuthentication

Remarque : Vous devez ajouter des associations de types de fichiers dans le manifeste de l’application pour déclarer les types de fichiers spécifiques auxquels votre application pourra accéder dans cet emplacement.		 Récupérez un dossier en utilisant :
StorageFolder.GetFolderFromPathAsync

Récupérez un fichier en utilisant :
StorageFile.GetFileFromPathAsync

Exemple

Cet exemple ajoute la fonctionnalité restreinte broadFileSystemAccess. Outre la spécification de la fonctionnalité, l’espace de noms rescap doit être ajouté, et il est également ajouté à IgnorableNamespaces.

<Package
  ...
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  IgnorableNamespaces="uap mp rescap">
...
<Capabilities>
    <rescap:Capability Name="broadFileSystemAccess" />
</Capabilities>

Notes

Pour obtenir la liste complète des fonctionnalités de l’application, consultez l’article Déclarations des fonctionnalités d’application.