Permissões de acesso a arquivoFile access permissions

Os aplicativos UWP (Plataforma Universal do Windows) podem acessar determinados locais do sistema de arquivos por padrão.Universal Windows Platform (UWP) apps can access certain file system locations by default. Os aplicativos também podem acessar outros locais por meio do seletor de arquivos ou da declaração de funcionalidades.Apps can also access additional locations through the file picker, or by declaring capabilities.

Locais que todos os aplicativos podem acessarLocations that all apps can access

Ao criar um novo aplicativo, por padrão, você pode acessar os seguintes locais do sistema de arquivos:When you create a new app, you can access the following file system locations by default:

Diretório de instalação do aplicativoApplication install directory

A pasta em que o aplicativo está instalado no sistema do usuário.The folder where your app is installed on the user's system.

Há duas maneiras principais de acessar arquivos e pastas no diretório de instalação de seu aplicativo:There are two primary ways to access files and folders in your app's install directory:

  1. Você pode recuperar um StorageFolder que represente o diretório de instalação do aplicativo, assim:You can retrieve a StorageFolder that represents your app's install directory, like this:

    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.You can then access files and folders in the directory using StorageFolder methods. No exemplo, esse StorageFolder é armazenado na variável installDirectory.In the example, this StorageFolder is stored in the installDirectory variable. 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.You can learn more about working with your app package and install directory from the App package information sample on GitHub.

  2. Você pode recuperar um arquivo diretamente do diretório de instalação do aplicativo usando um URI de aplicativo, assim:You can retrieve a file directly from your app's install directory by using an app URI, like this:

    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).When GetFileFromApplicationUriAsync completes, it returns a StorageFile that represents the file.txt file in the app's install directory (file in the example).

    O prefixo "ms-appx:///" no URI refere-se ao diretório de instalação do aplicativo.The "ms-appx:///" prefix in the URI refers to the app's install directory. Você pode aprender mais sobre como usar os URIs em Como usar URIs para conteúdo de referência.You can learn more about using app URIs in How to use URIs to reference content.

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.In addition, and unlike other locations, you can also access files in your app install directory by using some Win32 and COM for Universal Windows Platform (UWP) apps and some C/C++ Standard Library functions from Microsoft Visual Studio.

O diretório de instalação do aplicativo é um local somente leitura.The app's install directory is a read-only location. Você não pode obter acesso ao diretório de instalação através do seletor de arquivos.You can't gain access to the install directory through the file picker.

Localizações de dados de aplicativosApplication data locations

As pastas em que seu aplicativo pode armazenar dados.The folders where your app can store data. Essas pastas (local, móvel e temporária) são criadas quando o aplicativo é instalado.These folders (local, roaming and temporary) are created when your app is installed.

Há duas maneiras principais de acessar arquivos e pastas nos locais de dados de seu aplicativo:There are two primary ways to access files and folders from your app's data locations:

  1. Use as propriedades ApplicationData para recuperar uma pasta de dados do aplicativo.Use ApplicationData properties to retrieve an app data folder.

    Por exemplo, você pode usar o ApplicationData.LocalFolder para recuperar um StorageFolder que represente a pasta local do seu aplicativo assim:For example, you can use ApplicationData.LocalFolder to retrieve a StorageFolder that represents your app's local folder like this:

    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.If you want to access your app's roaming or temporary folder, use the RoamingFolder or TemporaryFolder property instead.

    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.After you retrieve a StorageFolder that represents an app data location, you can access files and folders in that location by using StorageFolder methods. No exemplo, esses objetos StorageFolder são armazenados na variável localFolder.In the example, these StorageFolder objects are stored in the localFolder variable. 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.You can learn more about using app data locations from the guidance on the ApplicationData class page, and by downloading the Application data sample from GitHub.

  2. Você pode recuperar um arquivo diretamente da pasta local do seu aplicativo usando um URI de aplicativo, assim:You can retrieve a file directly from your app's local folder by using an app URI, like this:

    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).When GetFileFromApplicationUriAsync completes, it returns a StorageFile that represents the file.txt file in the app's local folder (file in the example).

    O prefixo "ms-appdata:///local/" no URI refere-se à pasta local do aplicativo.The "ms-appdata:///local/" prefix in the URI refers to the app's local folder. Para acessar os arquivos nas pastas roaming ou temporárias do aplicativo, use "ms-appdata:///roaming/" ou "ms-appdata:///temporary/" em vez disso.To access files in the app's roaming or temporary folders use "ms-appdata:///roaming/" or "ms-appdata:///temporary/" instead. Você pode saber mais sobre como usar URIs do aplicativo em Como carregar recursos de arquivos.You can learn more about using app URIs in How to load file resources.

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.In addition, and unlike other locations, you can also access files in your app data locations by using some Win32 and COM for UWP apps and some C/C++ Standard Library functions from Visual Studio.

Você não pode acessar as pastas locais, roaming ou temporária com o seletor de arquivos.You can't access the local, roaming, or temporary folders through the file picker.

Dispositivos removíveisRemovable devices

Além disso, o aplicativo pode acessar alguns dos arquivos em dispositivos conectados por padrão.Additionally, your app can access some of the files on connected devices by default. 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.This is an option if your app uses the AutoPlay extension to launch automatically when users connect a device, like a camera or USB thumb drive, to their system. 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.The files your app can access are limited to specific file types that are specified via File Type Association declarations in your app manifest.

É 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.Of course, you can also gain access to files and folders on a removable device by calling the file picker (using FileOpenPicker and FolderPicker) and letting the user pick files and folders for your app to access. Saiba como usar o seletor de arquivos em Abrir arquivos e pastas com um seletor.Learn how to use the file picker in Open files and folders with a picker.

Observação

Para saber mais sobre como acessar um cartão SD ou outros dispositivos removíveis, veja Acessar o cartão SD.For more info about accessing an SD card or other removable devices, see Access the SD card.

Locais que aplicativos UWP podem acessarLocations that UWP apps can access

Pasta Downloads do usuárioUser's Downloads folder

A pasta em que os arquivos baixados são salvos por padrão.The folder where downloaded files are saved by default.

Por padrão, o aplicativo só pode acessar arquivos e pastas na pasta de Downloads do usuário que seu aplicativo criou.By default, your app can only access files and folders in the user's Downloads folder that your app created. 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.However, you can gain access to files and folders in the user's Downloads folder by calling a file picker (FileOpenPicker or FolderPicker) so that users can navigate and pick files or folders for your app to access.

  • Você pode criar um arquivo na pasta Downloads do usuário desta forma:You can create a file in the user's Downloads folder like this:

    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.DownloadsFolder.CreateFileAsync is overloaded so that you can specify what the system should do if there is already an existing file in the Downloads folder that has the same name. Quando esses métodos são concluídos, eles retornam um StorageFile que representa o arquivo que foi criado.When these methods complete, they return a StorageFile that represents the file that was created. Esse arquivo é chamado newFile no exemplo.This file is called newFile in the example.

  • Você pode criar uma subpasta na pasta Downloads do usuário desta forma:You can create a subfolder in the user's Downloads folder like this:

    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.DownloadsFolder.CreateFolderAsync is overloaded so that you can specify what the system should do if there is already an existing subfolder in the Downloads folder that has the same name. Quando esses métodos são concluídos, eles retornam um StorageFolder que representa a subpasta que foi criada.When these methods complete, they return a StorageFolder that represents the subfolder that was created. Esse arquivo é chamado newFolder no exemplo.This file is called newFolder in the example.

Acessando locais adicionaisAccessing additional locations

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.In addition to the default locations, an app can access additional files and folders by declaring capabilities in the app manifest or by calling a file picker to let the user pick files and folders for the app to access.

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.Apps that declare the AppExecutionAlias extension have file-system permissions from the directory that they are launched from in the console window, and downwards.

Retenção de acesso a arquivos e pastasRetaining access to files and folders

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.When your app retrieves a file or folder via a picker, a file activation, a drag-and-drop operation, etc. it only has access to that file or folder until the app is terminated. 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.If you would like to automatically access the file or folder in the future, you can add it to the FutureAccessList so that your app can readily access that item in the future. Você também pode usar a MostRecentlyUsedList para gerenciar com facilidade uma lista de arquivos usados recentemente.You can also use the MostRecentlyUsedList to easily manage a list of recently-used files.

Funcionalidades para acessar outros locaisCapabilities for accessing other locations

A tabela a seguir lista locais adicionais que você pode acessar declarando uma ou mais funcionalidades e usando a API Windows.Storage associada.The following table lists additional locations that you can access by declaring one or more capabilities and using the associated Windows.Storage API.

LocationLocation RecursoCapability API Windows.StorageWindows.Storage API
Todos os arquivos aos quais o usuário tem acesso.All files that the user has access to. Por exemplo: documentos, imagens, fotos, downloads, área de trabalho, OneDrive etc.For example: documents, pictures, photos, downloads, desktop, OneDrive, etc. broadFileSystemAccessbroadFileSystemAccess

Esta é uma funcionalidade restrita.This is a restricted capability. O acesso é configurável em Configurações > Privacidade > Sistema de arquivos.Access is configurable in Settings > Privacy > File system. 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.Because users can grant or deny the permission any time in Settings, you should ensure that your app is resilient to those changes. 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.If you find that your app does not have access, you may choose to prompt the user to change the setting by providing a link to the Windows 10 file system access and privacy article. Observe que o usuário deve fechar o aplicativo, mudar a configuração e reiniciar o aplicativo.Note that the user must close the app, toggle the setting, and restart the app. 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.If they toggle the setting while the app is running, the platform will suspend your app so that you can save the state, then forcibly terminate the app in order to apply the new setting. Na atualização de abril de 2018, o padrão para as permissões é Ativada.In the April 2018 update, the default for the permission is On. Na atualização de outubro de 2018, o padrão é Desativada.In the October 2018 update, the default is Off.

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.If you submit an app to the Store that declares this capability, you will need to supply additional descriptions of why your app needs this capability, and how it intends to use it.

Essa funcionalidade funciona para APIs no namespace Windows.Storage.This capability works for APIs in the Windows.Storage namespace. Consulte a seção Exemplo no final deste artigo para obter um exemplo de como habilitar essa funcionalidade em seu aplicativo.See the Example section at the end of this article for an example of how to enable this capability in your app.

Observação: Não há suporte para essa funcionalidade no Xbox.Note: This capability is not supported on Xbox.
N/Dn/a
DocumentosDocuments documentsLibrarydocumentsLibrary

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.Note: You must add File Type Associations to your app manifest that declare specific file types that your app can access in this location.

Use esse recurso se o seu aplicativo:Use this capability if your app:
- Possibilitar acesso offline entre plataformas ao conteúdo específico do OneDrive usando URLs válidas do OneDrive ou IDs de Recursos corretas- Facilitates cross-platform offline access to specific OneDrive content using valid OneDrive URLs or Resource IDs
– Salvar arquivos abertos no OneDrive do usuário automaticamente enquanto offline- Saves open files to the user's OneDrive automatically while offline
KnownFolders.DocumentsLibraryKnownFolders.DocumentsLibrary
MúsicaMusic musicLibrarymusicLibrary
Consulte também Arquivos e pastas nas bibliotecas Música, Fotos e Vídeos.Also see Files and folders in the Music, Pictures, and Videos libraries.
KnownFolders.MusicLibraryKnownFolders.MusicLibrary
ImagensPictures picturesLibrarypicturesLibrary
Consulte também Arquivos e pastas nas bibliotecas Música, Fotos e Vídeos.Also see Files and folders in the Music, Pictures, and Videos libraries.
KnownFolders.PicturesLibraryKnownFolders.PicturesLibrary
vídeosVideos videosLibraryvideosLibrary
Consulte também Arquivos e pastas nas bibliotecas Música, Fotos e Vídeos.Also see Files and folders in the Music, Pictures, and Videos libraries.
KnownFolders.VideosLibraryKnownFolders.VideosLibrary
Dispositivos removíveisRemovable devices removableStorageremovableStorage

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.Note You must add File Type Associations to your app manifest that declare specific file types that your app can access in this location.

Consulte também Acessar o cartão SD.Also see Access the SD card.
KnownFolders.RemovableDevicesKnownFolders.RemovableDevices
Bibliotecas de grupo domésticoHomegroup libraries Pelo menos um dos seguintes recursos é necessário.At least one of the following capabilities is needed.
- musicLibrary- musicLibrary
- picturesLibrary- picturesLibrary
- videosLibrary- videosLibrary
KnownFolders.HomeGroupKnownFolders.HomeGroup
Dispositivos do servidor de mídia (DLNA)Media server devices (DLNA) Pelo menos um dos seguintes recursos é necessário.At least one of the following capabilities is needed.
- musicLibrary- musicLibrary
- picturesLibrary- picturesLibrary
- videosLibrary- videosLibrary
KnownFolders.MediaServerDevicesKnownFolders.MediaServerDevices
Pastas UNC (Convenção de Nomenclatura Universal)Universal Naming Convention (UNC) folders Uma combinação dos seguintes recursos é necessária.A combination of the following capabilities is needed.

O recurso de redes de trabalho e domésticas:The home and work networks capability:
- privateNetworkClientServer- privateNetworkClientServer

E pelo menos um recurso de internet e de redes públicas:And at least one internet and public networks capability:
- internetClient- internetClient
- internetClientServer- internetClientServer

E, se aplicável, o recurso de credenciais de domínio:And, if applicable, the domain credentials capability:
- enterpriseAuthentication- 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.Note: You must add File Type Associations to your app manifest that declare specific file types that your app can access in this location.
Recupere uma pasta usando:Retrieve a folder using:
StorageFolder.GetFolderFromPathAsyncStorageFolder.GetFolderFromPathAsync

Recupere um arquivo usando:Retrieve a file using:
StorageFile.GetFileFromPathAsyncStorageFile.GetFileFromPathAsync

ExemploExample

Este exemplo adiciona a funcionalidade broadFileSystemAccess restrita.This example adds the restricted broadFileSystemAccess capability. Além de especificar a funcionalidade, o namespace rescap deve ser adicionado. Ele também é adicionado a IgnorableNamespaces.In addition to specifying the capability, the rescap namespace must be added, and is also added to IgnorableNamespaces.

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

Observação

Para obter uma lista completa de funcionalidades do aplicativo, veja Declarações de funcionalidades do aplicativo.For a complete list of app capabilities, see App capability declarations.