Compartilhar via

Trabalhar com arquivos

  • Artigo

Este tópico abrange o que você precisa saber para começar a leitura e gravação de arquivos em um aplicativo da UWP (Plataforma Universal do Windows). As principais APIs e os tipos são apresentados e os links são fornecidos para ajudar você a saber mais.

Este não é um tutorial. Se você quiser um tutorial, veja 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 ao arquivo, que mostra como criar, ler, gravar, copiar e excluir um arquivo, bem como recuperar propriedades de arquivo e lembrar-se de um arquivo ou pasta para que seu aplicativo pode acessá-lo facilmente novamente.

Vamos examinar o código para gravar e ler texto de um arquivo e como acessar as pastas locais, em roaming e temporárias do aplicativo.

O que você precisa saber

Veja os principais tipos que você precisa conhecer 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 estar acostumado a lidar com caminhos de cadeia de caracteres. Há algumas APIs do Windows Runtime que usam uma cadeia de caracteres, mas com mais frequência, você usará um StorageFile para representar um arquivo, pois alguns arquivos com os quais você trabalha na UWP podem não ter um caminho ou podem ter um caminho complicado. Use StorageFile.GetFileFromPathAsync() a fim de 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 fazer a leitura/gravação de uma matriz de bytes ou do conteúdo de um buffer. Essa classe é muito parecida com a classe PathIO. A principal diferença é que em vez de usar um caminho de cadeia de caracteres, como PathIO, 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, além de propriedades que fornecem informações sobre uma pasta.

As maneiras comuns de obter um StorageFolder incluem:

Gravar texto em um arquivo

Para essa introdução, o foco será em um cenário simples: a leitura e gravação de texto. Vamos começar analisando alguns códigos que usam 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, identifique o local em que o arquivo deve estar localizado. Windows.Storage.ApplicationData.Current.LocalFolder fornece acesso à pasta de dados local, que é criada para o aplicativo durante a instalação. Consulte Acessar o sistema de arquivos para obter detalhes sobre as pastas que o aplicativo pode acessar.

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

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

Ler texto de um arquivo

Assim como acontece na gravação, a leitura começa ao especificar o local em que o arquivo está. Vamos usar o mesmo local como no exemplo acima. Em seguida, vamos usar a classe FileIO para ler o 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 do pacote do aplicativo>\ para armazenar os arquivos locais, em roaming e temporários do aplicativo, entre outras coisas. O aplicativo não precisa declarar funcionalidades para acessar essas pastas, que não podem ser acessadas por outros aplicativos. Essas pastas também são removidas quando o aplicativo é desinstalado.

Veja algumas das pastas de aplicativo que você normalmente usará:

  • LocalState: para dados locais do dispositivo atual. Quando é feito o backup do dispositivo, os dados nesse 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 essa pasta com Windows.Storage.ApplicationData.Current.LocalFolder.Salve os dados locais que você não deseja que estejam no backup do OneDrive em LocalCacheFolder, que pode ser acessada com Windows.Storage.ApplicationData.Current.LocalCacheFolder.

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

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

Acessar o resto sistema de arquivos

Um aplicativo UWP deve declarar sua intenção de acessar uma biblioteca de usuário específica, adicionando a funcionalidade correspondente ao seu manifesto. Em seguida, quando o aplicativo for instalado, o usuário será solicitado a confirmar a autorização para acessar a biblioteca especificada. Caso contrário, o aplicativo não será instalado. Há recursos para acessar bibliotecas de música, fotos e vídeos. Consulte Declaração de funcionalidade do aplicativo para ver uma lista completa. Para obter um StorageFolder para essas bibliotecas, use a classe Windows.Storage.KnownFolders.

Biblioteca de documentos

Embora exista uma funcionalidade para acessar a biblioteca de documentos do usuário, essa funcionalidade é restrita, ou seja, um aplicativo que a declarar será rejeitado pela Microsoft Store, exceto quando você segue um processo para obter uma aprovação especial. Ela não se destina a uso geral. Em vez disso, use os seletores de arquivo ou pasta (veja Abrir arquivos e pastas com um seletor e Salvar um arquivo com um seletor) que permitem ao usuário navegar até a pasta ou o arquivo. Quando o usuário navega até um arquivo ou pasta, ele permite implicitamente que o aplicativo o acesse e o sistema permite o acesso.

Acesso geral

Como alternativa, o aplicativo pode declarar a funcionalidade restrita broadFileSystem em seu manifesto, 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 a intervenção de um seletor de arquivo ou pasta.

Para obter uma lista completa dos locais que os aplicativos podem acessar, consulte Permissões de acesso ao arquivo.

APIs e documentos úteis

Veja um resumo rápido de APIs e outras documentações úteis para ajudar você a começar a trabalhar com arquivos e pastas.

APIs úteis

API 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.
FileIO Fornece uma maneira fácil de ler e gravar texto. Essa classe também pode fazer a leitura/gravação de uma matriz de bytes ou do conteúdo de um buffer.
PathIO Fornece uma maneira fácil de fazer a leitura/gravação de texto de/para um arquivo considerando um caminho de cadeia de caracteres dele. Essa classe também pode fazer a leitura/gravação de uma matriz de bytes ou do conteúdo de um buffer.
DataReader e DataWriter Lê e grava 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, de roaming e de arquivos temporários.
Windows.Storage.Pickers.FolderPicker Permite que o usuário escolha uma pasta e retorna um StorageFolder para ele. É assim que você obtém acesso aos 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 para ele. É 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, a extensão e o local de armazenamento para 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 do Windows.Storage.Streams Abrange a leitura e gravação de fluxos. Analise especificamente as classes DataReader e DataWriter que fazem a leitura e gravação de buffers, bytes, inteiros, GUIDs, TimeSpans e muito mais.

Documentos úteis

Tópico Descrição
Namespace do Windows.Storage Documentos de referência da API.
Arquivos, pastas e bibliotecas Documentos conceituais.
Criar, gravar e ler um arquivo Aborda criação, leitura e gravação de texto, dados binários e fluxos.
Introdução ao armazenamento de dados de aplicativo localmente Além de abordar as melhores práticas para salvar os dados locais, abrange a finalidade da pasta LocalSettings e LocalCache.
Armazene e recupere configurações e outros dados de aplicativo Fornece uma visão geral de vários armazenamentos de dados de aplicativo, como as pastas locais, em roaming e temporárias.
Permissões de acesso a arquivo Informações sobre quais locais do sistema de arquivos o aplicativo pode acessar.
Abrir arquivos e pastas com um seletor Mostra como acessar arquivos e pastas permitindo que o usuário decida por meio de uma interface do usuário de seletor.
Windows.Storage.Streams Tipos usados para ler e gravar fluxos.
Arquivos e pastas nas bibliotecas Música, Fotos 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 de aplicativos Mostra como armazenar e recuperar dados específicos de cada usuário usando as APIs de dados de aplicativos.
Exemplo de acesso a arquivos Mostra como criar, ler, gravar, copiar e excluir um arquivo.
Exemplo do seletor de arquivos Mostra como acessar arquivos e pastas, permitindo que o usuário as escolha com a interface do usuário, e mostra como salvar um arquivo para que o usuário possa especificar o nome, o tipo e o local de um arquivo para salvar.
Exemplo de JSON Mostra como codificar e decodificar objetos JSON (JavaScript Object Notation), matrizes, cadeias de caracteres, números e boolianos usando o namespace Windows.Data.Json.
Exemplos de código adicionais Escolha Arquivos, pastas e bibliotecas na lista suspensa de categoria.