Accès au système de fichiers dans Xamarin.iOS

Vous pouvez utiliser Xamarin.iOS et les System.IO classes de la bibliothèque de classes de base .NET (BCL) pour accéder au système de fichiers iOS. La classe File permet de créer, supprimer et lire des fichiers, et la classe Directory permet de créer, supprimer ou énumérer le contenu des répertoires. Vous pouvez également utiliser Stream des sous-classes, qui peuvent fournir un plus grand degré de contrôle sur les opérations de fichier (telles que la compression ou la recherche de position dans un fichier).

iOS impose des restrictions sur ce qu’une application peut faire avec le système de fichiers pour préserver la sécurité des données d’une application et pour protéger les utilisateurs contre les applications malveillantes. Ces restrictions font partie du bac à sable d’application : ensemble de règles qui limitent l’accès d’une application aux fichiers, préférences, ressources réseau, matériel, etc. Une application est limitée à la lecture et à l’écriture de fichiers dans son répertoire de base (emplacement installé) ; il ne peut pas accéder aux fichiers d’une autre application.

IOS possède également certaines fonctionnalités spécifiques au système de fichiers : certains répertoires nécessitent un traitement spécial en ce qui concerne les sauvegardes et les mises à niveau, et les applications peuvent également partager des fichiers entre eux et l’application Fichiers (depuis iOS 11) et via iTunes.

Cet article décrit les fonctionnalités et restrictions du système de fichiers iOS et inclut un exemple d’application qui montre comment utiliser Xamarin.iOS pour exécuter des opérations de système de fichiers simples :

Accès général aux fichiers

Xamarin.iOS vous permet d’utiliser les classes .NET System.IO pour les opérations de système de fichiers sur iOS.

Les extraits de code suivants illustrent certaines opérations de fichier courantes. Vous les trouverez tous ci-dessous dans le fichier SampleCode.cs , dans l’exemple d’application de cet article.

Travailler avec des répertoires

Ce code énumère les sous-répertoires du répertoire actif (spécifiés par le paramètre ./" ), qui est l’emplacement de votre exécutable d’application. Votre sortie est une liste de tous les fichiers et dossiers déployés avec votre application (affichés dans la fenêtre de console pendant le débogage).

var directories = Directory.EnumerateDirectories("./");
foreach (var directory in directories) {
      Console.WriteLine(directory);
}

Lecture de fichiers

Pour lire un fichier texte, vous n’avez besoin que d’une seule ligne de code. Cet exemple affiche le contenu d’un fichier texte dans la fenêtre Sortie de l’application.

var text = File.ReadAllText("TestData/ReadMe.txt");
Console.WriteLine(text);

sérialisation XML

Bien que l’utilisation de l’espace de noms complet System.Xml dépasse la portée de cet article, vous pouvez facilement désérialiser un document XML à partir du système de fichiers à l’aide d’un StreamReader comme cet extrait de code :

using (TextReader reader = new StreamReader("./TestData/test.xml")) {
      XmlSerializer serializer = new XmlSerializer(typeof(MyObject));
      var xml = (MyObject)serializer.Deserialize(reader);
}

Pour plus d’informations, consultez la documentation relative à System.Xml et à la sérialisation. Consultez la documentation Xamarin.iOS sur l’éditeur de liens. Vous devrez souvent ajouter l’attribut [Preserve] aux classes que vous envisagez de sérialiser.

Création de fichiers et de répertoires

Cet exemple montre comment utiliser la Environment classe pour accéder au dossier Documents où nous pouvons créer des fichiers et des répertoires.

var documents =
 Environment.GetFolderPath (Environment.SpecialFolder.MyDocuments);
var filename = Path.Combine (documents, "Write.txt");
File.WriteAllText(filename, "Write this text into a file");

La création d’un répertoire est un processus similaire :

var documents =
 Environment.GetFolderPath (Environment.SpecialFolder.MyDocuments);
var directoryname = Path.Combine (documents, "NewDirectory");
Directory.CreateDirectory(directoryname);

Pour plus d’informations, consultez la référence de l’API System.IO.

Sérialisation de JSON

Json.NET est une infrastructure JSON hautes performances qui fonctionne avec Xamarin.iOS et est disponible sur NuGet. Ajoutez le package NuGet à votre projet d’application à l’aide d’Ajouter NuGet dans Visual Studio pour Mac :

Ensuite, ajoutez une classe pour agir comme modèle de données pour la sérialisation/désérialisation (dans ce cas Account.cs) :

using System;
using System.Collections.Generic;
using Foundation; // for Preserve attribute, which helps serialization with Linking enabled

namespace FileSystem
{
    [Preserve]
    public class Account
    {
        public string Email { get; set; }
        public bool Active { get; set; }
        public DateTime CreatedDate { get; set; }
        public List<string> Roles { get; set; }

        public Account() {
        }
    }
}

Enfin, créez une instance de la classe, sérialisez-la Account dans des données json et écrivez-la dans un fichier :

// Create a new record
var account = new Account(){
    Email = "monkey@xamarin.com",
    Active = true,
    CreatedDate = new DateTime(2015, 5, 27, 0, 0, 0, DateTimeKind.Utc),
    Roles = new List<string> {"User", "Admin"}
};

// Serialize object
var json = JsonConvert.SerializeObject(account, Newtonsoft.Json.Formatting.Indented);

// Save to file
var documents = Environment.GetFolderPath (Environment.SpecialFolder.MyDocuments);
var filename = Path.Combine (documents, "account.json");
File.WriteAllText(filename, json);

Pour plus d’informations sur l’utilisation de données json dans une application .NET, consultez la documentation de Json.NET.

Considérations spéciales

Malgré les similitudes entre les opérations de fichiers Xamarin.iOS et .NET, iOS et Xamarin.iOS diffèrent de .NET de certaines façons importantes.

Rendre les fichiers projet accessibles au moment de l’exécution

Par défaut, si vous ajoutez un fichier à votre projet, il ne sera pas inclus dans l’assembly final et ne sera donc pas disponible pour votre application. Pour inclure un fichier dans l’assembly, vous devez le marquer avec une action de génération spéciale, appelée Contenu.

Pour marquer un fichier à inclure, cliquez avec le bouton droit sur le ou les fichiers, puis choisissez Contenu de l’action > de génération dans Visual Studio pour Mac. Vous pouvez également modifier l’action de génération dans la feuille Propriétés du fichier.

Respect de la casse

Il est important de comprendre que le système de fichiers iOS respecte la casse. La sensibilité à la casse signifie que vos noms de fichiers et de répertoires doivent correspondre exactement : README.txt et readme.txt seraient considérés comme des noms de fichiers différents.

Cela peut prêter à confusion pour les développeurs .NET qui sont plus familiarisés avec le système de fichiers Windows, qui ne respecte pas la casse : les fichiers, fichiers, fichiers et fichiers font tous référence au même répertoire.

Séparateur de chemin d’accès

iOS utilise la barre oblique '/' comme séparateur de chemin d’accès (différent de Windows, qui utilise la barre oblique inverse '\').

En raison de cette différence déroutante, il est recommandé d’utiliser la System.IO.Path.Combine méthode, qui s’ajuste pour la plateforme actuelle, plutôt que de coder en dur un séparateur de chemin particulier. Il s’agit d’une étape simple qui rend votre code plus portable pour d’autres plateformes.

Bac à sable d’application

L’accès de votre application au système de fichiers (et d’autres ressources telles que les fonctionnalités réseau et matérielles) est limité pour des raisons de sécurité. Cette restriction est appelée bac à sable d’application. En termes de système de fichiers, votre application est limitée à la création et à la suppression de fichiers et de répertoires dans son répertoire de base.

Le répertoire de base est un emplacement unique dans le système de fichiers où votre application et toutes ses données sont stockées. Vous ne pouvez pas choisir (ou modifier) l’emplacement du répertoire de base de votre application ; Toutefois, iOS et Xamarin.iOS fournissent des propriétés et des méthodes pour gérer les fichiers et les répertoires à l’intérieur.

Offre groupée d’applications

Le bundle d’applications est le dossier qui contient votre application. Il se distingue des autres dossiers en ajoutant le suffixe .app au nom du répertoire. Votre ensemble d’applications contient votre fichier exécutable et tout le contenu (fichiers, images, etc.) nécessaires pour votre projet.

Lorsque vous accédez à votre ensemble d’applications dans Mac OS, il apparaît avec une icône différente de celle que vous voyez dans d’autres répertoires (et le suffixe .app est masqué). Toutefois, il s’agit simplement d’un répertoire normal que le système d’exploitation affiche différemment.

Pour afficher le bundle d’applications pour l’exemple de code, cliquez avec le bouton droit sur le projet dans Visual Studio pour Mac, puis sélectionnez Révéler dans Le Finder. Accédez ensuite au répertoire bin/ directory où vous devez trouver une icône d’application (similaire à la capture d’écran ci-dessous).

Cliquez avec le bouton droit sur cette icône et choisissez Afficher le contenu du package pour parcourir le contenu du répertoire Application Bundle. Le contenu s’affiche comme le contenu d’un répertoire normal, comme illustré ici :

L’offre groupée d’applications est ce qui est installé sur le simulateur ou sur votre appareil pendant les tests, et en fin de compte, ce qui est soumis à Apple pour inclusion dans l’App Store.

Répertoires d’applications

Lorsque votre application est installée sur un appareil, le système d’exploitation crée un répertoire de base pour votre application et crée un certain nombre de répertoires dans le répertoire racine de l’application qui sont disponibles pour une utilisation. Dans la mesure où iOS 8, les répertoires accessibles par l’utilisateur ne se trouvent pas dans la racine de l’application. Vous ne pouvez donc pas dériver les chemins d’accès du bundle d’applications à partir des répertoires utilisateur, ou inversement.

Ces répertoires, comment déterminer leur chemin et leurs objectifs sont répertoriés ci-dessous :

Cette capture d’écran montre la structure de répertoires dans une fenêtre Finder :

Accès à d’autres répertoires par programmation

Le répertoire et les exemples de fichiers précédents ont accédé au Documents répertoire. Pour écrire dans un autre répertoire, vous devez construire un chemin d’accès à l’aide de la syntaxe .." comme indiqué ici :

var documents = Environment.GetFolderPath (Environment.SpecialFolder.MyDocuments);
var library = Path.Combine (documents, "..", "Library");
var filename = Path.Combine (library, "WriteToLibrary.txt");
File.WriteAllText(filename, "Write this text into a file in Library");

La création d’un répertoire est similaire :

var documents = Environment.GetFolderPath (Environment.SpecialFolder.MyDocuments);
var library = Path.Combine (documents, "..", "Library");
var directoryname = Path.Combine (library, "NewLibraryDirectory");
Directory.CreateDirectory(directoryname);

Les chemins d’accès Caches aux répertoires peuvent tmp être construits comme suit :

var documents = Environment.GetFolderPath (Environment.SpecialFolder.MyDocuments);
var cache = Path.Combine (documents, "..", "Library", "Caches");
var tmp = Path.Combine (documents, "..", "tmp");

Partage avec l’application Fichiers

iOS 11 a introduit l’application Files - un navigateur de fichiers pour iOS qui permet à l’utilisateur de voir et d’interagir avec ses fichiers dans iCloud et également stocké par n’importe quelle application qui la prend en charge. Pour permettre à l’utilisateur d’accéder directement aux fichiers de votre application, créez une clé booléenne dans le fichier LSSupportsOpeningDocumentsInPlace Info.plist et définissez-le truesur , comme ici :

Le répertoire Documents de l’application sera désormais disponible pour la navigation dans l’application Fichiers. Dans l’application Fichiers , accédez à Sur Mon iPhone et chaque application avec des fichiers partagés sera visible. Les captures d’écran ci-dessous montrent à quoi ressemble l’exemple d’application :

Partage de fichiers avec l’utilisateur via iTunes

Les utilisateurs peuvent accéder aux fichiers dans le répertoire Documents de votre application en modifiant Info.plist et en créant une application qui prend en charge l’entrée de partage iTunes (UIFileSharingEnabled) dans la vue Source , comme illustré ici :

Ces fichiers sont accessibles dans iTunes lorsque l’appareil est connecté et que l’utilisateur choisit l’onglet Apps . Par exemple, la capture d’écran suivante montre les fichiers de l’application sélectionnée partagée via iTunes :

Les utilisateurs peuvent uniquement accéder aux éléments de niveau supérieur dans ce répertoire via iTunes. Ils ne peuvent pas voir le contenu des sous-répertoires (bien qu’ils puissent les copier sur leur ordinateur ou les supprimer). Par exemple, les fichiers GoodReader, PDF et EPUB peuvent être partagés avec l’application afin que les utilisateurs puissent les lire sur leurs appareils iOS.

Les utilisateurs qui modifient le contenu de leur dossier Documents peuvent provoquer des problèmes s’ils ne sont pas prudents. Votre application doit tenir compte de cette situation et être résiliente aux mises à jour destructrices du dossier Documents.

L’exemple de code de cet article crée un fichier et un dossier dans le dossier Documents (dans SampleCode.cs) et active le partage de fichiers dans le fichier Info.plist. Cette capture d’écran montre comment celles-ci apparaissent dans iTunes :

Reportez-vous à l’article Working with Images pour plus d’informations sur la définition d’icônes pour l’application et pour tous les types de documents personnalisés que vous créez.

Si la UIFileSharingEnabled clé est false ou non présente, le partage de fichiers est, par défaut, désactivé et les utilisateurs ne pourront pas interagir avec votre répertoire Documents.

Sauvegarde et restauration

Lorsqu’un appareil est sauvegardé par iTunes, tous les répertoires créés dans le répertoire de base de votre application sont enregistrés à l’exception des répertoires suivants :

• [ApplicationName].app : n’écrivez pas dans ce répertoire, car il est signé et doit donc rester inchangé après l’installation. Il peut contenir des ressources auxquelles vous accédez à partir de votre code, mais elles ne nécessitent pas de sauvegarde, car elles seraient restaurées en téléchargeant à nouveau l’application.
• Bibliothèque/caches : le répertoire du cache est destiné aux fichiers de travail qui n’ont pas besoin d’être sauvegardés.
• tmp : ce répertoire est utilisé pour les fichiers temporaires créés et supprimés lorsqu’il n’est plus nécessaire, ou pour les fichiers supprimés par iOS lorsqu’il a besoin d’espace.

La sauvegarde d’une grande quantité de données peut prendre beaucoup de temps. Si vous décidez de sauvegarder un document ou des données particulier, votre application doit utiliser les dossiers Documents et Bibliothèque. Pour les données ou fichiers temporaires qui peuvent être facilement récupérés à partir du réseau, utilisez les caches ou le répertoire tmp.

Conformité aux restrictions de sauvegarde iOS 5 iCloud

Apple a introduit la fonctionnalité sauvegarde iCloud avec iOS 5. Lorsque la sauvegarde iCloud est activée, tous les fichiers du répertoire de base de votre application (à l’exception des répertoires qui ne sont pas sauvegardés normalement, par exemple, le bundle d’applications et Cachestmp) sont sauvegardés sur des serveurs iCloud. Cette fonctionnalité fournit à l’utilisateur une sauvegarde complète si son appareil est perdu, volé ou endommagé.

Étant donné que iCloud fournit uniquement 5 Go d’espace libre à chaque utilisateur et évite d’utiliser inutilement la bande passante, Apple s’attend à ce que les applications sauvegardent uniquement les données générées par l’utilisateur essentielles. Pour vous conformer aux instructions de stockage de données iOS, vous devez limiter la quantité de données sauvegardées en respectant les éléments suivants :

• Stockez uniquement les données générées par l’utilisateur ou les données qui ne peuvent pas être recréées dans le répertoire Documents (qui est sauvegardé).
• Stockez toutes les autres données qui peuvent facilement être recréées ou re-téléchargées dans Library/Caches ou tmp (qui ne sont pas sauvegardées et peuvent être « nettoyées »).
• Si vous avez des fichiers qui peuvent être appropriés pour le ou tmp le Library/Caches dossier, mais que vous ne souhaitez pas être « nettoyé », stockez-les ailleurs (par exempleLibrary/YourData) et appliquez l’attribut « ne pas sauvegarder » pour empêcher les fichiers d’utiliser la bande passante de sauvegarde iCloud et l’espace de stockage. Ces données utilisent toujours de l’espace sur l’appareil. Vous devez donc la gérer soigneusement et la supprimer lorsque cela est possible.

L’attribut « ne pas sauvegarder » est défini à l’aide de la NSFileManager classe. Vérifiez que votre classe est using Foundation et appelez SetSkipBackupAttribute comme suit :

var documents = Environment.GetFolderPath (Environment.SpecialFolder.MyDocuments);
var filename = Path.Combine (documents, "LocalOnly.txt");
File.WriteAllText(filename, "This file will never get backed-up. It would need to be re-created after a restore or re-install");
NSFileManager.SetSkipBackupAttribute (filename, true); // backup will be skipped for this file

true Quand SetSkipBackupAttribute le fichier n’est pas sauvegardé, quel que soit le répertoire dans lequel il est stocké (même le Documents répertoire). Vous pouvez interroger l’attribut à l’aide de la GetSkipBackupAttribute méthode, et vous pouvez le réinitialiser en appelant la SetSkipBackupAttribute méthode avec false, comme suit :

NSFileManager.SetSkipBackupAttribute (filename, false); // file will be backed-up

Partage de données entre les applications iOS et les extensions d’application

Étant donné que les extensions d’application s’exécutent dans le cadre d’une application hôte (par opposition à leur application contenante), le partage de données n’est pas automatiquement inclus afin que le travail supplémentaire soit nécessaire. Les groupes d’applications sont le mécanisme utilisé par iOS pour permettre à différentes applications de partager des données. Si les applications ont été correctement configurées avec les droits et l’approvisionnement appropriés, elles peuvent accéder à un répertoire partagé en dehors de leur bac à sable iOS normal.

Configurer un groupe d’applications

L’emplacement partagé est configuré à l’aide d’un groupe d’applications, qui est configuré dans la section Certificats, Identificateurs et profils sur iOS Centre de développement. Cette valeur doit également être référencée dans le fichier Entitlements.plist de chaque projet.

Pour plus d’informations sur la création et la configuration d’un groupe d’applications, reportez-vous au guide des fonctionnalités du groupe d’applications .

Fichiers

L’application iOS et l’extension peuvent également partager des fichiers à l’aide d’un chemin d’accès de fichier commun (étant donné qu’ils ont été correctement configurés avec les droits et l’approvisionnement appropriés) :

var FileManager = new NSFileManager ();
var appGroupContainer =FileManager.GetContainerUrl ("group.com.xamarin.WatchSettings");
var appGroupContainerPath = appGroupContainer.Path

Console.WriteLine ("Group Path: " + appGroupContainerPath);

// use the path to create and update files
...

Mises à jour de la version de l’application

Lorsqu’une nouvelle version de votre application est téléchargée, iOS crée un répertoire de base et stocke le nouveau bundle d’applications dans celui-ci. IOS déplace ensuite les dossiers suivants de la version précédente de votre ensemble d’applications vers votre nouveau répertoire de base :

• Documents
• Bibliothèque

D’autres répertoires peuvent également être copiés et placés sous votre nouveau répertoire de base, mais ils ne sont pas garantis pour être copiés. Votre application ne doit donc pas s’appuyer sur ce comportement système.

Résumé

Cet article a montré que les opérations de système de fichiers avec Xamarin.iOS sont similaires à toute autre application .NET. Il a également introduit le bac à sable d’application et examiné les implications de sécurité qu’elle provoque. Ensuite, il a exploré le concept d’un bundle d’applications. Enfin, il a énuméré les répertoires spécialisés disponibles pour votre application et expliqué leurs rôles pendant les mises à niveau et les sauvegardes de l’application.

Liens connexes

• Guide de programmation du système de fichiers
• Inscription des types de fichiers pris en charge par votre application