Partilhar via

Trabalhar com ficheiros

Este tópico aborda o que você precisa saber para começar a ler e gravar em arquivos em um aplicativo da Plataforma Universal do Windows (UWP). 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, escrever 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, escrever, copiar e apagar um ficheiro, bem como recuperar propriedades de um ficheiro e guardar um ficheiro ou pasta para que a sua aplicação possa acessá-lo facilmente novamente.

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

O que precisa de saber

Aqui estão os principais tipos que você precisa saber sobre como ler ou escrever 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 Tempo de Execução do Windows 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 pesado. Use StorageFile.GetFileFromPathAsync() para converter um caminho de string em um StorageFile.

  • A classe FileIO fornece uma maneira fácil de ler e escrever texto. Essa classe também pode ler/gravar uma matriz de bytes ou o conteúdo de um buffer. Esta classe é muito semelhante à classe PathIO . A principal diferença é que, em vez de usar um caminho de texto, como PathIO faz, aceita 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.

As formas comuns de se obter um StorageFolder incluem:

Gravar texto em um arquivo

Para esta introdução, vamos nos concentrar 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 ser localizado. Windows.Storage.ApplicationData.Current.LocalFolder Fornece acesso à pasta de dados local, que é criada para seu aplicativo quando ele é instalado. Consulte aceder ao sistema de ficheiros para obter detalhes sobre as pastas que a sua aplicação pode aceder.

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 ficheiro

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

Aceda ao sistema de ficheiros

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

Pastas de aplicativos

Quando um aplicativo UWP é instalado, várias pastas são criadas em c:\users<user name>\AppData\Local\Packages<app package identifier>\ para armazenar, entre outras coisas, os arquivos locais, móveis e temporários do aplicativo. O aplicativo não precisa declarar nenhum recurso 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 aplicativos que você normalmente usará:

  • LocalState: 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 utilizador redefinir ou substituir o dispositivo, os dados serão restaurados. Aceda a esta pasta com Windows.Storage.ApplicationData.Current.LocalFolder. Guarde os dados locais que não pretende fazer cópia de segurança para o OneDrive na pasta LocalCacheFolder, que pode aceder com Windows.Storage.ApplicationData.Current.LocalCacheFolder.

  • RoamingState: Os dados armazenados aqui já não circulam entre dispositivos (desde o 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 Aplicações do Azure. O Serviço de Aplicativo do Azure é amplamente suportado, bem documentado, confiável e oferece 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. Aceda a esta pasta com Windows.Storage.ApplicationData.Current.TemporaryFolder.

Aceda ao resto do sistema de ficheiros

Um aplicativo UWP deve declarar sua intenção de acessar uma biblioteca de usuário específica adicionando o recurso correspondente ao seu manifesto. O usuário é então solicitado quando o aplicativo é instalado para verificar se eles autorizam o acesso à biblioteca especificada. Caso contrário, o aplicativo não está instalado. Há capacidades para aceder às bibliotecas de fotografias, vídeos e música. Consulte a declaração de capacidades da aplicação para obter uma lista completa. Para obter um StorageFolder para essas bibliotecas, use a classe Windows.Storage.KnownFolders.

Biblioteca de documentos

Embora haja um recurso para acessar a biblioteca de documentos do usuário, esse recurso é restrito, o que significa que um aplicativo declarando isso será rejeitado pela Microsoft Store, a menos que você siga um processo para obter aprovação especial. Não se destina a uso geral. Em vez disso, use os seletores de arquivos ou pastas (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 implicitamente deu permissão para o aplicativo acessá-lo e o sistema permite o acesso.

Acesso geral

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

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

APIs e documentos úteis

Aqui está um resumo rápido das APIs e outra documentação útil para ajudá-lo a começar a usar arquivos e pastas.

APIs úteis

API (Interface de Programação de Aplicações) 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.
Entrada/Saída de Ficheiros Fornece uma maneira fácil de ler e escrever texto. Essa classe também pode ler/gravar uma matriz de bytes ou o conteúdo de um buffer.
PathIO Fornece uma forma fácil de ler/escrever texto de/para um ficheiro, dado um caminho de cadeia de caracteres para o ficheiro. Essa classe também pode ler/gravar uma matriz de bytes ou o conteúdo de um buffer.
DataReader & DataWriter Ler e escrever buffers, bytes, inteiros, GUIDs, intervalos de tempo e mais, de/para um fluxo de dados.
Windows.Storage.ApplicationData.Current Fornece acesso às pastas criadas para o aplicativo, como a pasta local, a pasta móvel 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 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 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 Abrange fluxos de leitura e escrita. Em particular, observe as classes DataReader e DataWriter, que leem e escrevem buffers, bytes, inteiros, GUIDs, TimeSpans e muito mais.

Documentos úteis

Tópico Descrição
de namespace Windows.Storage Documentos de referência da API.
Ficheiros, pastas e bibliotecas Documentos conceptuais.
Criar, escrever e ler um ficheiro Abrange a criação, leitura e gravação de texto, dados binários e fluxos.
Introdução ao armazenamento de dados de aplicativos localmente Além de cobrir as práticas recomendadas para salvar dados locais, abrange 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 armazenamentos de dados de aplicativos, como as pastas local, móvel e temporária.
Permissões de acesso a arquivos Informações sobre quais locais do sistema de arquivos seu aplicativo pode acessar.
Abrir ficheiros e pastas com um seletor Mostra como aceder a ficheiros e pastas permitindo que o utilizador decida através de uma interface do seletor.
Windows.Storage.Streams Tipos usados para ler e gravar fluxos.
Ficheiros e pastas nas bibliotecas de 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
Exemplo de dados de aplicativo Mostra como armazenar e recuperar dados específicos de cada usuário usando as APIs de dados do aplicativo.
Exemplo de acesso a arquivos Mostra como criar, ler, escrever, copiar e excluir um arquivo.
Exemplo de seletor de arquivos 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.
de exemplo JSON Mostra como codificar e decodificar objetos, matrizes, cadeias de caracteres, números e booleanos JavaScript Object Notation (JSON) usando o namespace Windows.Data.Json.
Exemplos de código adicionais Escolha Arquivos, Pastas e Bibliotecas na lista de categorias.