Доступ к файловой системе в Xamarin.iOS

Вы можете использовать Xamarin.iOS и System.IO классы в библиотеке базовых классов .NET (BCL) для доступа к файловой системе iOS. Класс File позволяет создавать, удалять и считывать файлы, а класс и Directory — создавать, удалять или перечислять содержимое каталогов. Также можно использовать Stream подклассы, которые могут обеспечить большую степень контроля над операциями с файлами (например, сжатием или поиском позиции в файле).

IOS накладывает некоторые ограничения на то, что приложение может сделать с файловой системой, чтобы сохранить безопасность данных приложения и защитить пользователей от злокачественного приложения. Эти ограничения являются частью песочницы приложения — набор правил, ограничивающих доступ приложения к файлам, предпочтениям, сетевым ресурсам, оборудованию и т. д. Приложение ограничено чтением и записью файлов в своем домашнем каталоге (установленное расположение); он не может получить доступ к файлам другого приложения.

IOS также имеет некоторые функции файловой системы: некоторые каталоги требуют специального лечения в отношении резервных копий и обновлений, а приложения также могут совместно использовать файлы друг с другом и приложение "Файлы " (с iOS 11) и через iTunes.

В этой статье рассматриваются функции и ограничения файловой системы iOS, а также пример приложения, демонстрирующего использование Xamarin.iOS для выполнения некоторых простых операций файловой системы:

Общий доступ к файлам

Xamarin.iOS позволяет использовать классы .NET System.IO для операций файловой системы в iOS.

Приведенные ниже фрагменты кода иллюстрируют некоторые распространенные операции с файлами. Они находятся ниже в файле SampleCode.cs в примере приложения для этой статьи.

Работа с каталогами

Этот код перечисляет вложенные каталоги в текущем каталоге (указанный параметром "./), который является расположением исполняемого файла приложения. Выходные данные будут списком всех файлов и папок, развернутых с приложением (отображается в окне консоли во время отладки).

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

Чтение файлов

Для чтения текстового файла требуется только одна строка кода. В этом примере будет отображаться содержимое текстового файла в окне вывода приложения.

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

сериализация XML

Хотя работа с полным System.Xml пространством имен выходит за рамки этой статьи, вы можете легко десериализировать XML-документ из файловой системы с помощью StreamReader, как этот фрагмент кода:

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

Дополнительные сведения см. в документации по System.Xml и сериализации. См. документацию по компоновщику Xamarin.iOS. Часто необходимо добавить [Preserve] атрибут в классы, которые планируется сериализовать.

Создание файлов и каталогов

В этом примере показано, как использовать Environment класс для доступа к папке Documents, где можно создавать файлы и каталоги.

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

Создание каталога является аналогичным процессом:

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

Дополнительные сведения см. в справочнике по API System.IO.

Сериализация JSON

Json.NET — это высокопроизводительная платформа JSON, которая работает с Xamarin.iOS и доступна в NuGet. Добавьте пакет NuGet в проект приложения с помощью Add NuGet в Visual Studio для Mac:

Затем добавьте класс, который будет выступать в качестве модели данных для сериализации или десериализации (в данном случае 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() {
        }
    }
}

Наконец, создайте экземпляр Account класса, сериализируйте его в данные JSON и запишите его в файл:

// 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);

Дополнительные сведения о работе с данными JSON в приложении .NET см. в документации json.NET.

Примечания

Несмотря на сходство между операциями файлов Xamarin.iOS и .NET, iOS и Xamarin.iOS отличаются от .NET некоторыми важными способами.

Предоставление доступа к файлам проекта во время выполнения

По умолчанию при добавлении файла в проект он не будет включен в окончательную сборку и поэтому не будет доступен приложению. Чтобы включить файл в сборку, необходимо пометить его специальным действием сборки с именем Content.

Чтобы пометить файл для включения, щелкните правой кнопкой мыши файлы и выберите "Создать содержимое действия>" в Visual Studio для Mac. Вы также можете изменить действие сборки на листе свойств файла.

Учет регистра

Важно понимать, что файловая система iOS учитывает регистр. Конфиденциальность регистра означает, что имена файлов и каталогов должны совпадать точно — README.txt и readme.txt будут считаться различными именами файлов.

Это может быть запутано для разработчиков .NET, которые более знакомы с файловой системой Windows, что является нечувствительным — файлы, ФАЙЛЫ и файлы будут ссылаться на один каталог.

Разделитель пути

IOS использует косую черту вперед /" в качестве разделителя пути (который отличается от Windows, который использует обратную косую черту "\").

Из-за этой запутанной разницы рекомендуется использовать System.IO.Path.Combine метод, который корректирует текущую платформу, а не жесткий код определенного разделителя путей. Это простой шаг, который делает код более переносимым на другие платформы.

Песочница приложения

Доступ приложения к файловой системе (и другим ресурсам, таким как сетевые и аппаратные функции), ограничен по соображениям безопасности. Это ограничение называется песочницей приложения. С точки зрения файловой системы приложение ограничено созданием и удалением файлов и каталогов в домашнем каталоге.

Домашний каталог — это уникальное расположение в файловой системе, в которой хранится приложение и все его данные. Невозможно выбрать (или изменить) расположение домашнего каталога для приложения; однако iOS и Xamarin.iOS предоставляют свойства и методы для управления файлами и каталогами внутри.

Пакет приложений

Пакет приложений — это папка, содержащая приложение. Он отличается от других папок, добавив .app суффикс в имя каталога. Пакет приложений содержит исполняемый файл и все содержимое (файлы, изображения и т. д.), необходимые для проекта.

При переходе к пакету приложений в Mac OS он отображается с другим значком, чем в других каталогах (и .app суффикс скрыт). Однако это просто обычный каталог, который операционная система отображается по-другому.

Чтобы просмотреть пакет приложения для примера кода, щелкните проект правой кнопкой мыши в Visual Studio для Mac и выберите "Показать" в Finder. Затем перейдите к каталогу bin/ directory, где следует найти значок приложения (как показано на снимок экрана ниже).

Щелкните правой кнопкой мыши этот значок и выберите "Показать содержимое пакета", чтобы просмотреть содержимое каталога пакета приложений. Содержимое отображается так же, как содержимое регулярного каталога, как показано здесь:

Пакет приложений — это то, что установлено на симуляторе или на устройстве во время тестирования, и в конечном счете это то, что отправлено Apple для включения в App Store.

Каталоги приложений

Когда приложение установлено на устройстве, операционная система создает домашний каталог для приложения и создает ряд каталогов в корневом каталоге приложения, доступных для использования. Так как iOS 8 каталоги, доступные для пользователей, не находятся в корневом каталоге приложения, поэтому пути для пакета приложений нельзя получить из каталогов пользователей или наоборот.

Эти каталоги, как определить путь и их цели перечислены ниже.

На этом снимке экрана показана структура каталога в окне Finder:

Доступ к другим каталогам программным способом

Предыдущие примеры каталогов и файлов обращаются к каталогу Documents . Чтобы записать в другой каталог, необходимо создать путь с помощью синтаксиса ".". Как показано ниже:

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");

Создание каталога аналогично:

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

Пути к каталогам Caches и tmp каталогам можно создать следующим образом:

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

Общий доступ к приложению "Файлы"

В iOS 11 появилось приложение "Файлы " — браузер файлов для iOS, позволяющий пользователю просматривать и взаимодействовать с файлами в iCloud, а также храниться в любом приложении, поддерживающем его. Чтобы разрешить пользователю напрямую получать доступ к файлам в приложении, создайте логический ключ в файле LSSupportsOpeningDocumentsInPlace Info.plist и задайте его следующим trueобразом:

Каталог документов приложения теперь будет доступен для просмотра в приложении "Файлы". В приложении "Файлы" перейдите в раздел "Мой iPhone", а каждое приложение с общими файлами будет отображаться. На снимках экрана ниже показано, как выглядит пример приложения:

Совместное использование файлов с пользователем с помощью iTunes

Пользователи могут получить доступ к файлам в каталоге документов приложения, изменив Info.plist и создав приложение, которое поддерживает общий доступ iTunes (UIFileSharingEnabled) в представлении источника , как показано ниже:

Эти файлы можно получить в iTunes, когда устройство подключено, и пользователь выбирает вкладку Apps . Например, на следующем снимке экрана показаны файлы в выбранном приложении, к которым предоставлен общий доступ через iTunes:

Пользователи могут получить доступ только к элементам верхнего уровня в этом каталоге с помощью iTunes. Они не могут видеть содержимое любых подкаталогов (хотя они могут скопировать их на компьютер или удалить их). Например, с помощью GoodReader файлы PDF и EPUB можно предоставить приложению общий доступ, чтобы пользователи могли читать их на своих устройствах iOS.

Пользователи, изменяющие содержимое папки "Документы", могут вызвать проблемы, если они не осторожны. Ваше приложение должно учитывать это и быть устойчивым к разрушительным обновлениям папки "Документы".

Пример кода для этой статьи создает файл и папку в папке "Документы" (в SampleCode.cs) и включает общий доступ к файлам в файле Info.plist . На снимке экрана показано, как они отображаются в iTunes:

Сведения о настройке значков для приложения и любых пользовательских типов документов, создаваемых в статье "Работа с изображениями".

UIFileSharingEnabled Если ключ имеет значение false или отсутствует, общий доступ к файлам по умолчанию отключен, а пользователи не смогут взаимодействовать с каталогом Documents.

Резервное копирование и восстановление

При резервном копировании устройства с помощью iTunes все каталоги, созданные в домашнем каталоге приложения, будут сохранены, кроме следующих каталогов:

• [ApplicationName].app — не записывайте в этот каталог, так как он подписан и поэтому должен оставаться неизменным после установки. Он может содержать ресурсы, к которым вы обращаетесь из кода, но не требуют резервного копирования, так как они будут восстановлены путем повторной загрузки приложения.
• Библиотека и кэши — каталог кэша предназначен для рабочих файлов, которые не требуют резервного копирования.
• tmp — этот каталог используется для временных файлов, созданных и удаленных при отсутствии необходимости, или для файлов, которые iOS удаляет при необходимости пространства.

Резервное копирование большого объема данных может занять много времени. Если вы решили создать резервную копию любого документа или данных, приложение должно использовать папки "Документы и библиотека". Для временных данных или файлов, которые можно легко получить из сети, используйте кэши или каталог tmp.

Соблюдение ограничений резервного копирования iOS 5 iCloud

Apple представила функции резервного копирования iCloud с iOS 5. Если служба архивации iCloud включена, все файлы в домашнем каталоге приложения (за исключением каталогов, которые обычно не резервируются, например, пакет Cachesприложений и tmp) создают резервную копию на серверах iCloud. Эта функция предоставляет пользователю полную резервную копию в случае потери, кражи или повреждения устройства.

Так как iCloud предоставляет только 5 ГБ свободного места каждому пользователю и не требует необходимости использовать пропускную способность, Apple ожидает, что приложения будут резервное копирование только необходимых пользовательских данных. Чтобы соответствовать рекомендациям по хранилищу данных iOS, необходимо ограничить объем данных, которые будут резервированы, следуя приведенным ниже элементам:

• Храните только созданные пользователем данные или данные, которые в противном случае не могут быть повторно созданы, в каталоге "Документы" (резервное копирование которого выполняется).
• Храните любые другие данные, которые можно легко создать или повторно скачать или Library/Caches tmp (который не поддерживает резервное копирование и может быть "очищен").
• Если у вас есть файлы, которые могут быть подходящими для Library/Caches папки или tmp папки, но вы не хотите быть "чистыми", сохраните их в другом месте (например Library/YourData) и примените атрибут "не резервное копирование", чтобы предотвратить использование пропускной способности резервного копирования iCloud и места хранения. Эти данные по-прежнему используют пространство на устройстве, поэтому следует тщательно управлять им и удалять их, когда это возможно.

Атрибут "не резервного копирования" задается с помощью NSFileManager класса. Убедитесь, что класс является using Foundation и вызывается SetSkipBackupAttribute следующим образом:

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 Если SetSkipBackupAttribute файл не будет создавать резервную копию, независимо от каталога, в который он хранится (даже Documents каталог). Атрибут можно запросить с помощью GetSkipBackupAttribute метода, и его можно сбросить, вызвав SetSkipBackupAttribute метод следующим falseобразом:

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

Совместное использование данных между приложениями iOS и расширениями приложений

Так как расширения приложений выполняются как часть ведущего приложения (в отличие от их содержащего приложения), общий доступ к данным не включается автоматически, поэтому требуется дополнительная работа. Группы приложений — это механизм использования iOS для предоставления другим приложениям общего доступа к данным. Если приложения были правильно настроены с правильными правами и подготовкой, они могут получить доступ к общему каталогу за пределами обычной песочницы iOS.

Настройка группы приложений

Общее расположение настраивается с помощью группы приложений, настроенной в разделе "Сертификаты, идентификаторы и профили" в Центр разработки iOS. Это значение также должно ссылаться в файле "Права каждого проекта.plist".

Сведения о создании и настройке группы приложений см. в руководстве по возможностям группы приложений .

Файлы

Приложение iOS и расширение также могут совместно использовать файлы с помощью общего пути к файлу (учитывая, что они правильно настроены с правильными правами и подготовкой):

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
...

Обновления версий приложения

После скачивания новой версии приложения iOS создает новый домашний каталог и сохраняет в нем новый пакет приложений. Затем iOS перемещает следующие папки из предыдущей версии пакета приложений в новый домашний каталог:

• Документы
• Библиотека

Другие каталоги также могут быть скопированы и помещены в новый домашний каталог, но они не гарантированно копируются, поэтому ваше приложение не должно полагаться на это системное поведение.

Итоги

В этой статье показано, что операции файловой системы с Xamarin.iOS похожи на любое другое приложение .NET. Она также представила песочницу приложения и изучила последствия безопасности, которые она вызывает. Далее он изучил концепцию пакета приложений. Наконец, он перечислил специализированные каталоги, доступные вашему приложению, и объяснил их роли во время обновлений и резервных копий приложений.

Дополнительные ссылки

• Руководство по программированию файловой системы
• Регистрация типов файлов, поддерживаемых приложением