Работа с файлами Work with files

В этом разделе описывается,как приступить к чтению файлов и записи в файлы в приложении универсальной платформы Windows (UWP). This topic covers what you need to know to get started reading from, and writing to, files in a Universal Windows Platform (UWP) app. Здесь представлены основные интерфейсы API и типы, а также ссылки на дополнительные ресурсы. The main APIs and types are introduced, and links are provided to help you learn more.

Это не руководство. This is not a tutorial. Если вам необходимо полное руководство, ознакомьтесь с разделом Создание, запись и чтение файла, в котором показано, как создать, считать и записать файл, а также использовать буферы и потоки. If you want a tutorial, see Create, write, and read a file which, in addition to demonstrating how to create, read, and write a file, shows how to use buffers and streams. Вас также может заинтересовать пример доступа к файлам, в котором показано, как создать, считать, записать, скопировать и удалить файл, а также как получать свойства файла и запоминать файлу или папку, чтобы ваше приложение легко могло получить доступ к ним снова. You may also be interested in the File access sample which shows how to create, read, write, copy and delete a file, as well as how to retrieve file properties and remember a file or folder so that your app can easily access it again.

Мы рассмотрим код для записи текста в файл и чтения текста из файла, а также для получения доступа к локальным, перемещаемым и временным папкам приложения. We’ll look at code to write and read text from a file and how to access the app’s local, roaming, and temporary folders.

Что необходимо знать? What do you need to know

Ниже приведены основные типы, о которых нужно знать для чтения текста и записи текста в файл. Here are the main types you need to know about to read or write text from/to a file:

Windows.Storage.StorageFile представляет файл. Windows.Storage.StorageFile represents a file. Этот класс содержит свойства, которые предоставляют сведения о файле, и методы для создания, открытия, копирования, удаления и переименования файлов. This class has properties that provide information about the file, and methods for creating, opening, copying, deleting, and renaming files. Возможно, вы привыкли работать со строковыми путями. You may be used to dealing with string paths. Есть ряд API среды выполнения Windows, принимающих строковый путь, но чаще всего вы будете использовать объект StorageFile для представления файла, так как некоторые файлы на платформе UWP могут быть без пути или путь к ним может быть слишком длинным. There are some Windows Runtime APIs that take a string path, but more often you will use a StorageFile to represent a file because some files you work with in UWP may not have a path, or may have an unwieldy path. Используйте метод StorageFile.GetFileFromPathAsync() для преобразования строкового пути в объект StorageFile. Use StorageFile.GetFileFromPathAsync() to convert a string path to a StorageFile.

Класс FileIO предоставляет простой способ для чтения и записи текста. The FileIO class provides an easy way to read and write text. Этот класс также может читать и записывать массив байтов или содержимое буфера. This class can also read/write an array of bytes, or the contents of a buffer. Этот класс очень похож на класс PathIO. This class is very similar to the PathIO class. Основное различие заключается в том, что вместо использования строкового пути, как в PathIO, он принимает StorageFile. The main difference is that instead of taking a string path, as PathIO does, it takes a StorageFile.

Windows.Storage.StorageFolder представляет папку (каталог). Windows.Storage.StorageFolder represents a folder (directory). Этот класс содержит методы для создания файлов, запроса содержимого папки, создания, переименования и удаление папок, а также свойства, которые предоставляют сведения о папке. This class has methods for creating files, querying the contents of a folder, creating, renaming, and deleting folders, and properties that provide information about a folder.

Вот распространенные способы получения StorageFolder. Common ways to get a StorageFolder include:

• Windows.Storage.Pickers.FolderPicker позволяет пользователю перейти к требуемой папке. Windows.Storage.Pickers.FolderPicker which allows the user to navigate to the folder they want to use.
• Windows.Storage.ApplicationData.Current предоставляет объект StorageFolder для одной из локальных для приложения папок, например локальной, перемещаемой и временной папки. Windows.Storage.ApplicationData.Current which provides the StorageFolder specific to one of folders local to the app like the local, roaming, and temporary folder.
• Windows.Storage.KnownFolders предоставляет StorageFolder для известных библиотек, таких как «Музыка» и «Изображения». Windows.Storage.KnownFolders which provides the StorageFolder for known libraries such as the Music or Picture libraries.

Запись текста в файл Write text to a file

В рамках этого обзора мы рассмотрим простой сценарий: чтение и запись текста. For this introduction, we will focus on a simple scenario: reading and writing text. Начнем с кода, который использует класс FileIO, чтобы записать текст в файл. Let’s start by looking at some code that uses the FileIO class to write text to a file.

Сначала мы определим, где файл должен быть размещен. We first identify where the file should be located. Windows.Storage.ApplicationData.Current.LocalFolder предоставляет доступ к локальной папке данных, которая создается для приложения во время установки. Windows.Storage.ApplicationData.Current.LocalFolder provides access to the local data folder, which is created for your app when it is installed. Дополнительные сведения о папках, доступных вашему приложению, см. в разделе Доступ к файловой системе. See Access the file system for details about the folders your app can access.

Затем мы используем StorageFolder для создания файла (или его открытия, если он уже существует). Then, we use StorageFolder to create the file (or open it if it already exists).

Класс FileIO предоставляет удобный способ записи текста в файл. The FileIO class provides a convenient way to write text to the file. FileIO.WriteTextAsync() заменяет все содержимое файла предоставленным текстом. FileIO.WriteTextAsync() replaces the entire contents of the file with the provided text. FileIO.AppendLinesAsync() добавляет в файл коллекцию строк, записывая по одному строковому значению в каждую строку. FileIO.AppendLinesAsync() appends a collection of strings to the file—writing one string per line.

Чтение текста из файла Read text from a file

Как и при записи в файл, чтение файла начинается с указания его расположения. As with writing a file, reading a file starts with specifying where the file is located. Мы будем использовать то же расположение, что и в примере выше. We’ll use the same location as in the example above. Затем мы используем класс FileIO для чтения содержимого файла. Then we’ll use the FileIO class to read its contents.

Вы можете также считывать каждую строку файла в отдельные строки в коллекции с помощью IList contents = await Windows.Storage.FileIO.ReadLinesAsync(sampleFile); . You can also read each line of the file into individual strings in a collection with IList contents = await Windows.Storage.FileIO.ReadLinesAsync(sampleFile);

Доступ к файловой системе Access the file system

На платформе UWP доступ к папке ограничивается, чтобы обеспечить целостность и конфиденциальность данных пользователя. In the UWP platform, folder access is restricted to ensure the integrity and privacy of the user’s data.

Папки приложения App folders

Вот некоторые из папок приложения, которые часто используются. These are some of the app folders you will commonly use:

LocalState: для локальных на текущем устройстве данных. LocalState: For data local to the current device. При резервном копировании устройства данные в этом каталоге сохраняются в образе резервной копии в службе OneDrive. When the device is backed up, data in this directory is saved in a backup image in OneDrive. Если пользователь сбрасывает или заменяет устройство, эти данные будут восстановлены. If the user resets or replaces the device, the data will be restored. Для доступа к этой папке используйте Windows.Storage.ApplicationData.Current.LocalFolder. . Сохраните локальные данные, которые не требуется архивировать в OneDrive, в объекте LocalCacheFolder, к которому можно обратиться с помощью Windows.Storage.ApplicationData.Current.LocalCacheFolder . Access this folder with Windows.Storage.ApplicationData.Current.LocalFolder. Save local data that you don’t want backed up to OneDrive in the LocalCacheFolder, which you can access with Windows.Storage.ApplicationData.Current.LocalCacheFolder .

RoamingState: для данных, которые должны реплицироваться на всех устройствах, где установлено приложение. RoamingState: For data that should be replicated on all devices where the app is installed. Windows ограничивает объем данных, которые будут перемещаться, поэтому сохраняйте здесь только параметры пользователя и небольшие файлы. Windows limits the amount of data that will roam, so only save user settings and small files here. Для доступа к перемещаемой папке используйте Windows.Storage.ApplicationData.Current.RoamingFolder . Access the roaming folder with Windows.Storage.ApplicationData.Current.RoamingFolder .

TempState: для данных, которые могут быть удалены, когда приложение не выполняется. TempState: For data that may be deleted when the app isn’t running. Для доступа к этой папке используйте Windows.Storage.ApplicationData.Current.TemporaryFolder . Access this folder with Windows.Storage.ApplicationData.Current.TemporaryFolder .

Доступ к остальной части файловой системы Access the rest of the file system

Приложение UWP должно объявить свои намерения для доступа к определенной библиотеке пользователя, добавив соответствующую возможность в свой манифест. A UWP app must declare its intent to access a specific user library by adding the corresponding capability to its manifest. Затем при установке приложения пользователям предлагается подтвердить, что они разрешили доступ к указанной библиотеке. The user is then prompted when the app is installed to verify that they authorize accessing the specified library. Если это не так, приложение не устанавливается. If not, the app is not installed. Существуют возможности для доступа к библиотекам изображений, видео и музыки. There are capabilities to access the pictures, videos, and music libraries. Полный список доступен в разделе Объявление возможностей приложения. See App capability declaration for a full list. Чтобы получить StorageFolder для этих библиотек, используйте класс Windows.Storage.KnownFolders. To get a StorageFolder for these libraries, use the Windows.Storage.KnownFolders class.

Библиотека документов Documents library

Хотя и существует возможность доступа к библиотеке документов пользователя, она ограничена, то есть приложение, которое ее объявит, будет отклонено в Microsoft Store, если вы не выполните процедуру получения специального разрешения. Although there is a capability to access the user’s documents library, that capability is restricted which means that an app declaring it will be rejected by the Microsoft Store unless you follow a process to get special approval. Оно не предназначено для общего использования. It is not intended for general use. Вместо этого используйте средства выбора файла или папки (см. разделы Открытие файлов и папок с помощью средства выбора и Сохранение файла с помощью средства выбора), позволяющие пользователям перейти к папке или файлу. Instead, use the file or folder pickers (see Open files and folders with a picker and Save a file with a picker) which allow the user to navigate to the folder or file. При переходе пользователей к файлу или папке они неявно разрешают приложению доступ к ним, и система разрешает доступ. When the user navigates to a folder or file, they have implicitly given permission for the app to access it and the system allows access.

Общий доступ General access

Кроме того, ваше приложение может объявить ограниченную возможность broadFileSystem в манифесте, которая также должна быть утверждена в Microsoft Store. Alternatively, your app can declare the restricted broadFileSystem capability in its manifest, which also requires Microsoft Store approval. Затем приложение сможет получить доступ к любому файлу, к которому обращается пользователь, без вмешательства средства выбора файла или папки. Then the app can access any file that the user has access to without requiring the intervention of a file or folder picker.

Полный список расположений, которые доступны приложениям, приведен в разделе Разрешения на доступ к файлам. For a comprehensive list of the locations that apps can access, see File access permissions.

Полезные интерфейсы API и документы Useful APIs and docs

Ниже приведено краткое описание интерфейсов API и другая полезная документация, которая поможет вам приступить к работе с файлами и папками. Here is a quick summary of APIs, and other useful documentation, to help get you started with files and folders.

Практическое руководство. Сжатие и извлечение файлов How to: Compress and extract files

Пространство имен System.IO.Compression предоставляет следующие типы для сжатия и распаковки файлов и потоков. The System.IO.Compression namespace contains the following types for compressing and decompressing files and streams. Вы также можете использовать эти типы для чтения и изменения содержимого сжатого файла. You can also use these types to read and modify the contents of a compressed file.

В примерах ниже показано несколько операций для работы со сжатыми файлами. The following examples show some of the operations you can perform with compressed files. Для этих примеров требуется добавить в проект следующие пакеты NuGet: These examples require the following NuGet packages to be added to your project:

Если вы используете .NET Framework, добавьте в проект ссылки на эти две библиотеки: If you’re using .NET Framework, add references to these two libraries to your project:

Пример 1: Создание и извлечение ZIP-файла Example 1: Create and extract a .zip file

В следующем примере показано, как создавать и извлекать сжатый файл .zip с помощью класса ZipFile. The following example shows how to create and extract a compressed .zip file by using the ZipFile class. Он сжимает содержимое папки в новый ZIP-файл и затем извлекает его в новую папку. The example compresses the contents of a folder into a new .zip file, and then extracts the zip to a new folder.

Чтобы запустить пример, создайте папку start в папке программы и заполните ее файлами для сжатия. To run the sample, create a start folder in your program folder and populate it with files to zip.

Пример 2: Извлечение файлов с определенными расширениями Example 2: Extract specific file extensions

В этом примере выполняется итерация по содержимому существующего ZIP-файла и извлекаются файлы с расширением .txt. The next example iterates through the contents of an existing .zip file and extracts files that have a .txt extension. Здесь используется класс ZipArchive для доступа к ZIP-файлу и класс ZipArchiveEntry для проверки отдельных элементов. It uses the ZipArchive class to access the zip, and the ZipArchiveEntry class to inspect the individual entries. Метод расширения ExtractToFile для объекта ZipArchiveEntry доступен в классе System.IO.Compression.ZipFileExtensions. The extension method ExtractToFile for the ZipArchiveEntry object is available in the System.IO.Compression.ZipFileExtensions class.

Чтобы запустить пример, поместите ZIP-файл с именем result.zip в папку программы. To run the sample, place a .zip file called result.zip in your program folder. По запросу укажите имя папки для извлечения. When prompted, provide a folder name to extract to.

При распаковке файлов важно убедиться в отсутствии вредоносных путей, которые могут вести за пределы каталога, в который вы извлекаете файлы. When unzipping files, you must look for malicious file paths, which can escape out of the directory you unzip into. Такая атака известна как обход путей. This is known as a path traversal attack. В следующем примере показано, как правильно проверить наличие вредоносных путей и безопасно извлечь файлы. The following example demonstrates how to check for malicious file paths and provides a safe way to unzip.

Пример 3. Добавление файла в существующий ZIP-файл Example 3: Add a file to an existing zip

В следующем примере используется класс ZipArchive для доступа к существующему ZIP-файлу и добавления в него файла. The following example uses the ZipArchive class to access an existing .zip file, and adds a file to it. Новый файл сжимается при добавлении в существующий ZIP-файл. The new file gets compressed when you add it to the existing zip.

Пример 4. Сжатие и распаковка GZ-файлов Example 4: Compress and decompress .gz files

Также вы можете использовать классы GZipStream и DeflateStream для сжатия и распаковки данных. You can also use the GZipStream and DeflateStream classes to compress and decompress data. Они применяют тот же алгоритм сжатия. They use the same compression algorithm. Вы можете распаковать объекты GZipStream, которые записаны в GZ-файл, с помощью многих распространенных средств. You can decompress GZipStream objects that are written to a .gz file by using many common tools. В следующем примере показано, как использовать класс GZipStream для сжатия и распаковки каталога файлов. The following example shows how to compress and decompress a directory of files by using the GZipStream class: