Compartilhar via

Trabalhar com arquivos

Este tópico aborda o que você precisa saber para começar a ler e gravar arquivos em um aplicativo UWP (Plataforma Universal do Windows). As principais APIs e tipos são introduzidos e links são fornecidos para ajudá-lo a saber mais.

Este não é um tutorial. Se você quiser um tutorial, consulte Criar, gravar e ler um arquivo que, além de demonstrar como criar, ler e gravar um arquivo, mostra como usar buffers e fluxos. Você também pode estar interessado no exemplo de acesso a arquivos que mostra como criar, ler, gravar, copiar e excluir um arquivo, bem como como recuperar propriedades de arquivo e lembrar de um arquivo ou pasta para que seu aplicativo possa acessá-lo facilmente novamente.

Examinaremos o código para gravar e ler texto de um arquivo e como acessar as pastas locais, móveis e temporárias do aplicativo.

O que você precisa saber

Aqui estão os principais tipos que você precisa saber para ler ou gravar texto de/para um arquivo:

  • Windows.Storage.StorageFile representa um arquivo. Essa classe tem propriedades que fornecem informações sobre o arquivo e métodos para criar, abrir, copiar, excluir e renomear arquivos. Você pode ser usado para lidar com caminhos de cadeia de caracteres. Há algumas APIs do Windows Runtime que usam um caminho de cadeia de caracteres, mas, com mais frequência, você usará um StorageFile para representar um arquivo porque alguns arquivos com os quais você trabalha na UWP podem não ter um caminho ou podem ter um caminho desordado. Use StorageFile.GetFileFromPathAsync() para converter um caminho de cadeia de caracteres em um StorageFile.

  • A classe FileIO fornece uma maneira fácil de ler e gravar texto. Essa classe também pode ler/gravar uma matriz de bytes ou o conteúdo de um buffer. Essa classe é muito semelhante à classe PathIO . A principal diferença é que, em vez de usar um caminho de cadeia de caracteres, como o PathIO faz, ele usa um StorageFile.

  • Windows.Storage.StorageFolder representa uma pasta (diretório). Essa classe tem métodos para criar arquivos, consultar o conteúdo de uma pasta, criar, renomear e excluir pastas e propriedades que fornecem informações sobre uma pasta.

Maneiras comuns de se obter uma StorageFolder incluem:

  • Windows.Storage.Pickers.FolderPicker , que permite que o usuário navegue até a pasta que deseja usar.
  • Windows.Storage.ApplicationData.Current que fornece o StorageFolder específico para uma das pastas locais do aplicativo, como a pasta local, a pasta roaming e a pasta temporária.
  • Windows.Storage.KnownFolders, que fornece o StorageFolder para bibliotecas conhecidas, como as bibliotecas música ou imagem.

Gravar texto em um arquivo

Para esta introdução, nos concentraremos em um cenário simples: ler e escrever texto. Vamos começar examinando algum código que usa a classe FileIO para gravar texto em um arquivo.

Windows.Storage.StorageFolder storageFolder = Windows.Storage.ApplicationData.Current.LocalFolder;
Windows.Storage.StorageFile file = await storageFolder.CreateFileAsync("test.txt",
        Windows.Storage.CreationCollisionOption.OpenIfExists);

await Windows.Storage.FileIO.WriteTextAsync(file, "Example of writing a string\r\n");

// Append a list of strings, one per line, to the file
var listOfStrings = new List<string> { "line1", "line2", "line3" };
await Windows.Storage.FileIO.AppendLinesAsync(file, listOfStrings); // each entry in the list is written to the file on its own line.

Primeiro, identificamos onde o arquivo deve estar localizado. Windows.Storage.ApplicationData.Current.LocalFolder fornece acesso à pasta de dados local, que é criada para seu aplicativo quando ele é instalado. Consulte Acessar o sistema de arquivos para obter detalhes sobre as pastas que seu aplicativo pode acessar.

Em seguida, usamos StorageFolder para criar o arquivo (ou abri-lo se ele já existir).

A classe FileIO fornece uma maneira conveniente de gravar texto no arquivo. FileIO.WriteTextAsync() substitui todo o conteúdo do arquivo pelo texto fornecido. FileIO.AppendLinesAsync() acrescenta uma coleção de cadeias de caracteres ao arquivo– gravando uma cadeia de caracteres por linha.

Ler texto de um arquivo

Assim como na gravação de um arquivo, a leitura de um arquivo começa com a especificação de onde o arquivo está localizado. Usaremos o mesmo local que no exemplo acima. Em seguida, usaremos a classe FileIO para ler seu conteúdo.

Windows.Storage.StorageFolder storageFolder = Windows.Storage.ApplicationData.Current.LocalFolder;
Windows.Storage.StorageFile file = await storageFolder.GetFileAsync("test.txt");

string text = await Windows.Storage.FileIO.ReadTextAsync(file);

Você também pode ler cada linha do arquivo em cadeias de caracteres individuais em uma coleção com IList<string> contents = await Windows.Storage.FileIO.ReadLinesAsync(sampleFile);

Acessar o sistema de arquivos

Na plataforma UWP, o acesso à pasta é restrito para garantir a integridade e a privacidade dos dados do usuário.

Pastas de aplicativo

Quando um aplicativo UWP é instalado, várias pastas são criadas em c:\users<nome de usuário>\AppData\Local\Packages<identificador de pacote do aplicativo>\ para armazenar, entre outras coisas, os arquivos locais, de roaming e temporários do aplicativo. O aplicativo não precisa declarar nenhuma funcionalidade para acessar essas pastas e essas pastas não são acessíveis por outros aplicativos. Essas pastas também são removidas quando o aplicativo é desinstalado.

Estas são algumas das pastas de aplicativo que você normalmente usará:

  • LocalState: Para dados locais do dispositivo atual. Quando o dispositivo faz backup, os dados neste diretório são salvos em uma imagem de backup no OneDrive. Se o usuário redefinir ou substituir o dispositivo, os dados serão restaurados. Acesse esta pasta com Windows.Storage.ApplicationData.Current.LocalFolder.. Salve dados locais que você não deseja fazer backup no OneDrive na LocalCacheFolder, que você pode acessar com Windows.Storage.ApplicationData.Current.LocalCacheFolder.

  • RoamingState: os dados armazenados aqui não são mais móveis (a partir do Windows 11), mas a pasta ainda está disponível. Acesse a pasta de roaming com Windows.Storage.ApplicationData.Current.RoamingFolder. A substituição recomendada é Serviço de Aplicativo do Azure. O Serviço de Aplicativo do Azure é amplamente compatível, bem documentado, confiável e dá suporte a cenários entre plataformas/ecossistemas, como iOS, Android e Web.

  • TempState: para dados que podem ser excluídos quando o aplicativo não está em execução. Acesse esta pasta com Windows.Storage.ApplicationData.Current.TemporaryFolder.

Acessar o restante do sistema de arquivos

Um aplicativo UWP deve declarar sua intenção de acessar uma biblioteca de usuários específica adicionando a funcionalidade correspondente ao manifesto. Em seguida, o usuário é solicitado quando o aplicativo é instalado para verificar se ele autoriza o acesso à biblioteca especificada. Caso contrário, o aplicativo não está instalado. Há recursos para acessar as imagens, vídeos e bibliotecas de música. Para uma lista completa, consulte a declaração de capacidade do aplicativo . Para obter um StorageFolder para essas bibliotecas, use a classe Windows.Storage.KnownFolders.

Biblioteca de documentos

Embora haja uma capacidade de acessar a biblioteca de documentos do usuário, essa funcionalidade é restrita, o que significa que um aplicativo que o declara será rejeitado pela Microsoft Store, a menos que você siga um processo para obter aprovação especial. Ele não se destina ao uso geral. Em vez disso, use os seletores de arquivo ou pasta (consulte Abrir arquivos e pastas com um seletor e salvar um arquivo com um seletor) que permitem que o usuário navegue até a pasta ou arquivo. Quando o usuário navega para uma pasta ou arquivo, ele tem implicitamente dado permissão para o aplicativo acessá-lo e o sistema permite o acesso.

Acesso geral

Como alternativa, seu aplicativo pode declarar a capacidade restrita broadFileSystem em seu manifesto, o que também requer aprovação da Microsoft Store. Em seguida, o aplicativo pode acessar qualquer arquivo ao qual o usuário tenha acesso sem exigir a intervenção de um seletor de arquivo ou pasta.

Para obter uma lista abrangente dos locais que os aplicativos podem acessar, consulte as permissões de acesso a arquivos.

APIs e documentos úteis

Aqui está um resumo rápido das APIs e outras documentações úteis para ajudar você a começar a usar arquivos e pastas.

APIs úteis

API (Interface de Programação de Aplicativos) Descrição
Windows.Storage.StorageFile Fornece informações sobre o arquivo e métodos para criar, abrir, copiar, excluir e renomear arquivos.
Windows.Storage.StorageFolder Fornece informações sobre a pasta, métodos para criar arquivos e métodos para criar, renomear e excluir pastas.
do FileIO Fornece uma maneira fácil de ler e gravar texto. Essa classe também pode ler/gravar uma matriz de bytes ou o conteúdo de um buffer.
PathIO Fornece uma maneira fácil de ler/gravar texto de/para um arquivo dado uma string como caminho para o arquivo. Essa classe também pode ler/gravar uma matriz de bytes ou o conteúdo de um buffer.
DataReader & DataWriter Ler e gravar buffers, bytes, inteiros, GUIDs, TimeSpans e muito mais, de/para um fluxo.
Windows.Storage.ApplicationData.Current Fornece acesso às pastas criadas para o aplicativo, como a pasta local, a pasta de roaming e a pasta de arquivos temporários.
Windows.Storage.Pickers.FolderPicker Permite que o usuário escolha uma pasta e retorna uma StorageFolder para ela. É assim que você obtém acesso a locais que o aplicativo não pode acessar por padrão.
Windows.Storage.Pickers.FileOpenPicker Permite que o usuário escolha um arquivo para abrir e retorna um StorageFile correspondente ao arquivo escolhido. É assim que você obtém acesso a um arquivo que o aplicativo não pode acessar por padrão.
Windows.Storage.Pickers.FileSavePicker Permite que o usuário escolha o nome do arquivo, a extensão e o local de armazenamento de um arquivo. Retorna um StorageFile. É assim que você salva um arquivo em um local que o aplicativo não pode acessar por padrão.
namespace Windows.Storage.Streams Aborda a leitura e gravação de fluxos. Em particular, considere as classes DataReader e DataWriter, que leem e gravam buffers, bytes, inteiros, GUIDs, TimeSpans e muito mais.

Documentos úteis

Tópico Descrição
Namespace Windows.Storage Documentos de referência da API.
arquivos, pastas e bibliotecas Documentos conceituais.
Criar, gravar e ler um arquivo Aborda a criação, leitura e gravação de texto, dados binários e fluxos.
Introdução ao armazenamento de dados do aplicativo localmente Além de abranger as práticas recomendadas para salvar dados locais, aborda a finalidade da pasta LocalSettings e LocalCache.
Armazenar e recuperar configurações e outros dados do aplicativo Fornece uma visão geral dos vários repositórios de dados do aplicativo, como as pastas locais, móveis e temporárias.
permissões de acesso ao arquivo Informações sobre quais locais do sistema de arquivos seu aplicativo pode acessar.
Abrir arquivos e pastas com um seletor Mostra como acessar arquivos e pastas permitindo que o usuário decida através de uma interface de seleção.
Windows.Storage.Streams Tipos usados para ler e gravar fluxos.
Arquivos e pastas nas bibliotecas Música, Imagens e Vídeos Aborda como remover pastas de bibliotecas, obter a lista de pastas em uma biblioteca e descobrir fotos, músicas e vídeos armazenados.

Exemplos de código úteis

Exemplo de código Descrição
Amostra de dados do aplicativo Mostra como armazenar e recuperar dados específicos para cada usuário usando as APIs de dados do aplicativo.
exemplo de acesso a arquivos Mostra como criar, ler, gravar, copiar e excluir um arquivo.
exemplo de seletor de arquivo Mostra como acessar arquivos e pastas permitindo que o usuário os escolha com a interface do usuário e como salvar um arquivo para que o usuário possa especificar o nome, o tipo de arquivo e o local de um arquivo a ser salvo.
Exemplo de JSON Mostra como codificar e decodificar objetos JSON (JavaScript Object Notation), matrizes, cadeias de caracteres, números e booleanos usando o namespace Windows.Data.Json.
Exemplos de código adicionais Escolha Arquivos, pastas e bibliotecas na lista suspensa de categorias.