Работа с файлами 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.

Как открыть файлы с помощью OpenFileDialog How to: Open files with the OpenFileDialog

System.Windows.Forms.OpenFileDialogКомпонент открывает диалоговое окно Windows для обзора и выбора файлов. The System.Windows.Forms.OpenFileDialog component opens the Windows dialog box for browsing and selecting files. Чтобы открыть и прочитать выбранные файлы, можно использовать OpenFileDialog.OpenFile метод или создать экземпляр System.IO.StreamReader класса. To open and read the selected files, you can use the OpenFileDialog.OpenFile method, or create an instance of the System.IO.StreamReader class. В следующих примерах показаны оба подхода. The following examples show both approaches.

В .NET Framework для получения или задания FileName свойства требуется уровень привилегий, предоставляемый System.Security.Permissions.FileIOPermission классом. In .NET Framework, to get or set the FileName property requires a privilege level granted by the System.Security.Permissions.FileIOPermission class. В примерах выполняется FileIOPermission Проверка разрешений и может вызываться исключение из-за недостаточных привилегий при выполнении в контексте частичного доверия. The examples run a FileIOPermission permission check, and can throw an exception due to insufficient privileges if run in a partial-trust context. Дополнительные сведения см. в статье основы управления доступом для кода. For more information, see Code access security basics.

Вы можете собрать и запустить эти примеры как .NET Framework приложения из командной строки C# или Visual Basic. You can build and run these examples as .NET Framework apps from the C# or Visual Basic command line. Дополнительные сведения см. в разделе Построение из командной строки с помощью csc.exe или Сборка из командной строки. For more information, see Command-line building with csc.exe or Build from the command line.

Начиная с .NET Core 3,0, можно также создавать и запускать примеры как приложения Windows .NET Core из папки с файлом проекта .NET Core Windows Forms . csproj . Starting with .NET Core 3.0, you can also build and run the examples as Windows .NET Core apps from a folder that has a .NET Core Windows Forms .csproj project file.

Пример. чтение файла в виде потока с помощью StreamReader Example: Read a file as a stream with StreamReader

В следующем примере используется Button обработчик событий Windows Forms элемента управления Click для открытия OpenFileDialog с помощью ShowDialog метода. The following example uses the Windows Forms Button control’s Click event handler to open the OpenFileDialog with the ShowDialog method. После того как пользователь выберет файл и нажмет кнопку ОК, экземпляр StreamReader класса считывает файл и отображает его содержимое в текстовом поле формы. After the user chooses a file and selects OK, an instance of the StreamReader class reads the file and displays its contents in the form’s text box. Дополнительные сведения о чтении из файловых потоков см FileStream.BeginRead . в разделе и FileStream.Read . For more information about reading from file streams, see FileStream.BeginRead and FileStream.Read.

Пример. Открытие файла из отфильтрованного выделенного фрагмента с помощью OpenFile Example: Open a file from a filtered selection with OpenFile

В следующем примере Button обработчик событий элемента управления используется Click для открытия OpenFileDialog с фильтром, который отображает только текстовые файлы. The following example uses the Button control’s Click event handler to open the OpenFileDialog with a filter that shows only text files. После того как пользователь выберет текстовый файл и нажмет кнопку ОК, OpenFile для открытия файла в блокноте используется метод. After the user chooses a text file and selects OK, the OpenFile method is used to open the file in Notepad.