Permissões de acesso a arquivo

Artigo
07/13/2023

Os aplicativos UWP (Plataforma Universal do Windows) podem acessar determinados locais do sistema de arquivos por padrão. Os aplicativos também podem acessar outros locais por meio do seletor de arquivos ou da declaração de funcionalidades.

Locais que aplicativos UWP podem acessar

Ao criar um novo aplicativo, por padrão, você pode acessar os seguintes locais do sistema de arquivos:

Diretório de instalação do aplicativo

A pasta em que o aplicativo está instalado no sistema do usuário.

Há duas maneiras principais de acessar arquivos e pastas no diretório de instalação de seu aplicativo:

Você pode recuperar um StorageFolder que represente o diretório de instalação do aplicativo, assim:

Windows.Storage.StorageFolder installedLocation = Windows.ApplicationModel.Package.Current.InstalledLocation;

var installDirectory = Windows.ApplicationModel.Package.current.installedLocation;

#include <winrt/Windows.Storage.h>
...
Windows::Storage::StorageFolder installedLocation{ Windows::ApplicationModel::Package::Current().InstalledLocation() };

Windows::Storage::StorageFolder^ installedLocation = Windows::ApplicationModel::Package::Current->InstalledLocation;

Você pode acessar arquivos e pastas no diretório usando métodos StorageFolder. No exemplo, esse StorageFolder é armazenado na variável installDirectory. Você pode saber mais sobre como trabalhar com o pacote do aplicativo e o diretório de instalação em Exemplo de informações de pacote do aplicativo no GitHub.

Você pode recuperar um arquivo diretamente do diretório de instalação do aplicativo usando um URI de aplicativo, assim:

using Windows.Storage;            
StorageFile file = await StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appx:///file.txt"));

Windows.Storage.StorageFile.getFileFromApplicationUriAsync("ms-appx:///file.txt").done(
    function(file) {
        // Process file
    }
);

Windows::Foundation::IAsyncAction ExampleCoroutineAsync()
{
    Windows::Storage::StorageFile file{
        co_await Windows::Storage::StorageFile::GetFileFromApplicationUriAsync(Windows::Foundation::Uri{L"ms-appx:///file.txt"})
    };
    // Process file
}

auto getFileTask = create_task(StorageFile::GetFileFromApplicationUriAsync(ref new Uri("ms-appx:///file.txt")));
getFileTask.then([](StorageFile^ file) 
{
    // Process file
});

Quando o GetFileFromApplicationUriAsync é concluído, ele retorna um StorageFile que representa o arquivo file.txt no diretório de instalação do aplicativo (no exemplo, file).

O prefixo "ms-appx:///" no URI refere-se ao diretório de instalação do aplicativo. Você pode aprender mais sobre como usar os URIs em Como usar URIs para conteúdo de referência.

Além disso, diferentemente de outros locais, você também pode acessar os arquivos no diretório de instalação de seu aplicativo usando Win32 e COM para aplicativos UWP (Plataforma Universal do Windows) e algumas funções da Biblioteca Padrão do C/C++ do Microsoft Visual Studio.

O diretório de instalação do aplicativo é um local somente leitura. Você não pode obter acesso ao diretório de instalação através do seletor de arquivos.

Acessar localizações de dados do aplicativo

As pastas em que seu aplicativo pode armazenar dados. Essas pastas (local, móvel e temporária) são criadas quando o aplicativo é instalado.

Há duas maneiras principais de acessar arquivos e pastas nos locais de dados de seu aplicativo:

Use as propriedades ApplicationData para recuperar uma pasta de dados do aplicativo.

Por exemplo, você pode usar o ApplicationData.LocalFolder para recuperar um StorageFolder que represente a pasta local do seu aplicativo assim:
```
using Windows.Storage;
StorageFolder localFolder = ApplicationData.Current.LocalFolder;
```
```
var localFolder = Windows.Storage.ApplicationData.current.localFolder;
```
```
Windows::Storage::StorageFolder storageFolder{
    Windows::Storage::ApplicationData::Current().LocalFolder()
};
```
```
using namespace Windows::Storage;
StorageFolder^ storageFolder = ApplicationData::Current->LocalFolder;
```
Se você quiser acessar o roaming do seu aplicativo ou uma pasta temporária, use a propriedade RoamingFolder ou TemporaryFolder.

Depois que você recuperar um StorageFolder que represente um local de dados do aplicativo, você pode acessar arquivos e pastas nesse local usando os métodos StorageFolder. No exemplo, esses objetos StorageFolder são armazenados na variável localFolder. Você pode saber mais sobre como usar locais de dados de aplicativos nas diretrizes da página Classe ApplicationData e ao baixar o Exemplo de dados de aplicativos do GitHub.

Você pode recuperar um arquivo diretamente da pasta local do seu aplicativo usando um URI de aplicativo, assim:

using Windows.Storage;
StorageFile file = await StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appdata:///local/file.txt"));

Windows.Storage.StorageFile.getFileFromApplicationUriAsync("ms-appdata:///local/file.txt").done(
    function(file) {
        // Process file
    }
);

Windows::Storage::StorageFile file{
    co_await Windows::Storage::StorageFile::GetFileFromApplicationUriAsync(Windows::Foundation::Uri{ L"ms-appdata:///local/file.txt" })
};
// Process file

using Windows::Storage;
auto getFileTask = create_task(StorageFile::GetFileFromApplicationUriAsync(ref new Uri("ms-appdata:///local/file.txt")));
getFileTask.then([](StorageFile^ file) 
{
    // Process file
});

Quando o GetFileFromApplicationUriAsync é concluído, ele retorna um StorageFile que representa o arquivo file.txt na pasta local do aplicativo(no exemplo, file).

O prefixo "ms-appdata:///local/" no URI refere-se à pasta local do aplicativo. Para acessar os arquivos nas pastas roaming ou temporárias do aplicativo, use "ms-appdata:///roaming/" ou "ms-appdata:///temporary/" em vez disso. Você pode saber mais sobre como usar URIs do aplicativo em Como carregar recursos de arquivos.

Além disso, diferentemente de outros locais, você também pode acessar os arquivos nos locais de dados de seu aplicativo usando Win32 e COM para aplicativos UWP e algumas funções da Biblioteca Padrão C/C++ do Visual Studio.

Você não pode acessar as pastas locais, roaming ou temporária com o seletor de arquivos.

Acessar dispositivos removíveis

Além disso, o aplicativo pode acessar alguns dos arquivos em dispositivos conectados por padrão. Esta é uma opção se o seu aplicativo usa a extensão de Dispositivo AutoPlay para ser iniciada automaticamente quando os usuários conectam um dispositivo, como uma câmera ou pen drive USB, ao seu sistema. Os arquivos que seu aplicativo podem acessar são limitados a determinados tipos de arquivos que são especificados através de declarações Associação de Tipo de Arquivos no manifesto do aplicativo.

É claro que você também pode obter acesso a arquivos e pastas em um dispositivo removível chamando o seletor de arquivos (usando o FileOpenPicker e o FolderPicker) e permitindo que o usuário escolha os arquivos e pastas para seu aplicativo acessar. Saiba como usar o seletor de arquivos em Abrir arquivos e pastas com um seletor.

Observação

Para saber mais sobre como acessar um cartão SD ou outros dispositivos removíveis, veja Acessar o cartão SD.

Pasta Downloads do usuário

A pasta em que os arquivos baixados são salvos por padrão.

Por padrão, o aplicativo só pode acessar arquivos e pastas na pasta de Downloads do usuário que seu aplicativo criou. No entanto, você pode ter acesso a arquivos e pastas na pasta Downloads do usuário chamando um seletor de arquivos (FileOpenPicker ou FolderPicker) de modo que os usuários possam navegar e escolher arquivos ou pastas para seu aplicativo acessar.

Você pode criar um arquivo na pasta Downloads do usuário desta forma:

using Windows.Storage;
StorageFile newFile = await DownloadsFolder.CreateFileAsync("file.txt");

Windows.Storage.DownloadsFolder.createFileAsync("file.txt").done(
    function(newFile) {
        // Process file
    }
);

Windows::Storage::StorageFile newFile{
    co_await Windows::Storage::DownloadsFolder::CreateFileAsync(L"file.txt")
};
// Process file

using Windows::Storage;
auto createFileTask = create_task(DownloadsFolder::CreateFileAsync(L"file.txt"));
createFileTask.then([](StorageFile^ newFile)
{
    // Process file
});

DownloadsFolder.CreateFileAsync é sobrecarregado de modo que você possa especificar o que o sistema deverá fazer se já houver um arquivo existente na pasta Downloads com o mesmo nome. Quando esses métodos são concluídos, eles retornam um StorageFile que representa o arquivo que foi criado. Esse arquivo é chamado newFile no exemplo.

Você pode criar uma subpasta na pasta Downloads do usuário desta forma:

using Windows.Storage;
StorageFolder newFolder = await DownloadsFolder.CreateFolderAsync("New Folder");

Windows.Storage.DownloadsFolder.createFolderAsync("New Folder").done(
    function(newFolder) {
        // Process folder
    }
);

Windows::Storage::StorageFolder newFolder{
    co_await Windows::Storage::DownloadsFolder::CreateFolderAsync(L"New Folder")
};
// Process folder

using Windows::Storage;
auto createFolderTask = create_task(DownloadsFolder::CreateFolderAsync(L"New Folder"));
createFolderTask.then([](StorageFolder^ newFolder)
{
    // Process folder
});

DownloadsFolder.CreateFolderAsync é sobrecarregado de modo que você possa especificar o que o sistema deverá fazer se já houver uma subpasta existente na pasta Downloads com o mesmo nome. Quando esses métodos são concluídos, eles retornam um StorageFolder que representa a subpasta que foi criada. Esse arquivo é chamado newFolder no exemplo.

Acessando locais adicionais

Além dos locais padrão, um aplicativo pode acessar arquivos e pastas adicionais declarando as funcionalidades no manifesto do aplicativo ou chamando um seletor de arquivos para permitir que o usuário selecione os arquivos e as pastas para o aplicativo acessar.

Os aplicativos que declaram a extensão AppExecutionAlias têm permissões do sistema de arquivos do diretório no qual são iniciados na janela do console e nos subdiretórios.

Retenção de acesso a arquivos e pastas

Quando o aplicativo recupera um arquivo ou uma pasta por meio de um seletor, uma ativação de arquivo, uma operação do tipo "arrastar e soltar" etc., ele só tem acesso a esse arquivo ou pasta até que o aplicativo seja encerrado. Se quiser acessar automaticamente o arquivo ou a pasta no futuro, você poderá adicioná-lo à FutureAccessList para que o aplicativo possa acessar esse item prontamente no futuro. Você também pode usar a MostRecentlyUsedList para gerenciar com facilidade uma lista de arquivos usados recentemente.

Funcionalidades para acessar outros locais

A tabela a seguir lista locais adicionais que você pode acessar declarando uma ou mais funcionalidades e usando a API Windows.Storage associada.

Location	Recurso	API Windows.Storage
Todos os arquivos aos quais o usuário tem acesso. Por exemplo: documentos, imagens, fotos, downloads, área de trabalho, OneDrive etc.	broadFileSystemAccess Esta é uma funcionalidade restrita. O acesso é configurável em Configurações>Privacidade>Sistema de arquivos. Como os usuários podem conceder ou negar a permissão a qualquer momento em Configurações, você deve garantir que seu aplicativo seja resiliente a essas alterações. Se você achar que seu aplicativo não tem acesso, você poderá optar por solicitar que o usuário altere a configuração fornecendo um link para o artigo Acesso e privacidade do sistema de arquivos do Windows 10. Observe que o usuário deve fechar o aplicativo, mudar a configuração e reiniciar o aplicativo. Se a configuração for mudada enquanto o aplicativo estiver em execução, a plataforma suspenderá o aplicativo para que você possa salvar o estado e, em seguida, forçará o encerramento do aplicativo para aplicar a nova configuração. Na atualização de abril de 2018, o padrão para as permissões é Ativada. Na atualização de outubro de 2018, o padrão é Desativada. Se você enviar um aplicativo que declare essa funcionalidade para a Store, precisará fornecer descrições adicionais do motivo pelo qual seu aplicativo precisa dessa funcionalidade e como ele pretende usá-la. Essa funcionalidade funciona para APIs no namespace Windows.Storage. Consulte a seção Exemplo no final deste artigo para obter um exemplo de como habilitar essa funcionalidade em seu aplicativo. Observação: Não há suporte para essa funcionalidade no Xbox.	N/D
Documentos	documentsLibrary Observação: você deve adicionar Associações de tipo de arquivo ao manifesto do aplicativo que declarem tipos específicos de arquivos que seu aplicativo pode acessar neste local. Use esse recurso se o seu aplicativo: - Possibilitar acesso offline entre plataformas ao conteúdo específico do OneDrive usando URLs válidas do OneDrive ou IDs de Recursos corretas – Salvar arquivos abertos no OneDrive do usuário automaticamente enquanto offline	KnownFolders.DocumentsLibrary
Música	musicLibrary Consulte também Arquivos e pastas nas bibliotecas Música, Fotos e Vídeos.	KnownFolders.MusicLibrary
Imagens	picturesLibrary Consulte também Arquivos e pastas nas bibliotecas Música, Fotos e Vídeos.	KnownFolders.PicturesLibrary
vídeos	videosLibrary Consulte também Arquivos e pastas nas bibliotecas Música, Fotos e Vídeos.	KnownFolders.VideosLibrary
Dispositivos removíveis	removableStorage Observação: você deve adicionar Associações de tipo de arquivo ao manifesto do aplicativo que declarem tipos específicos de arquivos que seu aplicativo pode acessar neste local. Consulte também Acessar o cartão SD.	KnownFolders.RemovableDevices
Bibliotecas de grupo doméstico	Pelo menos um dos seguintes recursos é necessário. - musicLibrary - picturesLibrary - videosLibrary	KnownFolders.HomeGroup
Dispositivos do servidor de mídia (DLNA)	Pelo menos um dos seguintes recursos é necessário. - musicLibrary - picturesLibrary - videosLibrary	KnownFolders.MediaServerDevices
Pastas UNC (Convenção de Nomenclatura Universal)	Uma combinação dos seguintes recursos é necessária. O recurso de redes de trabalho e domésticas: - privateNetworkClientServer E pelo menos um recurso de internet e de redes públicas: - internetClient - internetClientServer E, se aplicável, o recurso de credenciais de domínio: - enterpriseAuthentication Observação: você deve adicionar Associações de tipo de arquivo ao manifesto do aplicativo que declarem tipos específicos de arquivos que seu aplicativo pode acessar neste local.	Recupere uma pasta usando: StorageFolder.GetFolderFromPathAsync Recupere um arquivo usando: StorageFile.GetFileFromPathAsync

Exemplo

Este exemplo adiciona a funcionalidade broadFileSystemAccess restrita. Além de especificar a funcionalidade, o namespace rescap deve ser adicionado. Ele também é adicionado a IgnorableNamespaces.

<Package
  ...
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  IgnorableNamespaces="uap mp rescap">
...
<Capabilities>
    <rescap:Capability Name="broadFileSystemAccess" />
</Capabilities>