Autorizzazioni di accesso ai file

Le app WinUI possono accedere a determinati percorsi del file system per impostazione predefinita. Le app possono anche accedere a percorsi aggiuntivi tramite la selezione file o dichiarando funzionalità.

Percorsi a cui le app WinUI possono accedere

Quando si crea una nuova app, è possibile accedere ai percorsi del file system seguenti per impostazione predefinita:

Directory di installazione dell'applicazione

Cartella in cui è installata l'app nel sistema dell'utente.

Esistono due modi principali per accedere a file e cartelle nella directory di installazione dell'app:

È possibile recuperare un oggetto StorageFolder che rappresenta la directory di installazione dell'app, come illustrato di seguito:
```
Windows.Storage.StorageFolder installedLocation = Windows.ApplicationModel.Package.Current.InstalledLocation;
```
```
#include <winrt/Windows.Storage.h>
...
Windows::Storage::StorageFolder installedLocation{ Windows::ApplicationModel::Package::Current().InstalledLocation() };
```
È quindi possibile accedere a file e cartelle nella directory usando i metodi StorageFolder . Nell'esempio, l'oggetto StorageFolder viene archiviato nella installDirectory variabile . Per altre informazioni sull'uso del pacchetto dell'app e sull'installazione della directory, vedere l'esempio di informazioni sul pacchetto dell'app in GitHub.
È possibile recuperare un file direttamente dalla directory di installazione dell'app usando un URI dell'app, come illustrato di seguito:
```
using Windows.Storage;            
StorageFile file = await StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appx:///file.txt"));
```
```
Windows::Foundation::IAsyncAction ExampleCoroutineAsync()
{
    Windows::Storage::StorageFile file{
        co_await Windows::Storage::StorageFile::GetFileFromApplicationUriAsync(Windows::Foundation::Uri{L"ms-appx:///file.txt"})
    };
    // Process file
}
```
Quando GetFileFromApplicationUriAsync viene completato, restituisce un StorageFile che rappresenta il file.txt file nella directory di installazione dell'app (file nell'esempio).

Il prefisso "ms-appx:///" nell'URI fa riferimento alla directory di installazione dell'app. Per altre informazioni sull'uso degli URI dell'app, vedere Come usare gli URI per fare riferimento al contenuto.

Inoltre, a differenza di altre posizioni, è anche possibile accedere ai file nella directory di installazione dell'app usando alcune interfacce Win32 e COM per le app WinUI e alcune funzioni della libreria standard C/C++ di Microsoft Visual Studio.

La directory di installazione dell'app è un percorso di sola lettura. Non è possibile accedere alla directory di installazione tramite la selezione file.

Accedere ai percorsi dei dati dell'applicazione

Le cartelle in cui l'app può archiviare i dati. Queste cartelle (locale, roaming e temporaneo) vengono create al momento dell'installazione dell'app.

Esistono due modi principali per accedere a file e cartelle dai percorsi dei dati dell'app:

Usare le proprietà ApplicationData per recuperare una cartella dati dell'app.

Ad esempio, è possibile usare ApplicationData. LocalFolder per recuperare un oggetto StorageFolder che rappresenta la cartella locale dell'app come segue:
```
using Windows.Storage;
StorageFolder localFolder = ApplicationData.Current.LocalFolder;
```
```
Windows::Storage::StorageFolder storageFolder{
    Windows::Storage::ApplicationData::Current().LocalFolder()
};
```
Se vuoi accedere alla cartella mobile o temporanea dell'app, usa invece la proprietà RoamingFolder o TemporaryFolder .

Dopo aver recuperato un oggetto StorageFolder che rappresenta un percorso dati dell'app, è possibile accedere a file e cartelle in tale posizione usando i metodi StorageFolder. Nell'esempio questi oggetti StorageFolder vengono archiviati nella localFolder variabile . Per altre informazioni sull'uso dei percorsi dei dati delle app, vedere le linee guida nella pagina della classe ApplicationData e scaricare l'esempio di dati dell'applicazione da GitHub.
Puoi recuperare un file direttamente dalla cartella locale dell'app usando un URI dell'app, come illustrato di seguito:
```
using Windows.Storage;
StorageFile file = await StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appdata:///local/file.txt"));
```
```
Windows::Storage::StorageFile file{
    co_await Windows::Storage::StorageFile::GetFileFromApplicationUriAsync(Windows::Foundation::Uri{ L"ms-appdata:///local/file.txt" })
};
// Process file
```
Al termine di GetFileFromApplicationUriAsync , restituisce un oggetto StorageFile che rappresenta il file.txt file nella cartella locale dell'app (file nell'esempio).

Il prefisso "ms-appdata:///local/" nell'URI fa riferimento alla cartella locale dell'app. Per accedere ai file nelle cartelle mobili o temporanee dell'app, usare invece "ms-appdata:///roaming/" o "ms-appdata:///temporary/". Per altre informazioni sull'uso degli URI dell'app, vedere Come caricare le risorse dei file.

Inoltre, e diversamente da altri percorsi, è possibile accedere anche ai file nei percorsi dei dati dell'app utilizzando alcune API Win32 e COM per le app WinUI e alcune funzioni della libreria standard C/C++ disponibili in Visual Studio.

Non è possibile accedere alle cartelle locali, mobili o temporanee tramite la selezione file.

Accedere ai dispositivi rimovibili

Inoltre, l'app può accedere ad alcuni dei file nei dispositivi connessi per impostazione predefinita. Questa è un'opzione se l'app usa l'estensione AutoPlay per l'avvio automatico quando gli utenti connettono un dispositivo, ad esempio una fotocamera o un'unità usb, al sistema. I file a cui l'app può accedere sono limitati a tipi di file specifici specificati tramite dichiarazioni di associazione di tipi di file nel manifesto dell'app.

Naturalmente, puoi anche accedere a file e cartelle in un dispositivo rimovibile chiamando la selezione file (usando FileOpenPicker e FolderPicker) e consentendo all'utente di selezionare file e cartelle per l'accesso all'app. Informazioni su come usare la selezione file in Apri file e cartelle con una selezione.

Annotazioni

Per altre info sull'accesso a una scheda SD o ad altri dispositivi rimovibili, vedi Accedere alla scheda SD.

Cartella Download dell'utente

La cartella in cui i file scaricati vengono salvati per impostazione predefinita.

Per impostazione predefinita, l'app può accedere solo a file e cartelle nella cartella Download dell'utente creata dall'app. Tuttavia, puoi accedere a file e cartelle nella cartella Download dell'utente chiamando una selezione file (FileOpenPicker o FolderPicker) in modo che gli utenti possano esplorare e selezionare file o cartelle a cui accedere l'app.

È possibile creare un file nella cartella Download dell'utente come segue:
```
using Windows.Storage;
StorageFile newFile = await DownloadsFolder.CreateFileAsync("file.txt");
```
```
Windows::Storage::StorageFile newFile{
    co_await Windows::Storage::DownloadsFolder::CreateFileAsync(L"file.txt")
};
// Process file
```
DownloadsFolder. CreateFileAsync è sottoposto a overload in modo da poter specificare le operazioni che il sistema deve eseguire se è già presente un file esistente nella cartella Download con lo stesso nome. Al termine di questi metodi, restituiscono un oggetto StorageFile che rappresenta il file creato. Questo file viene chiamato newFile nell'esempio.
È possibile creare una sottocartella nella cartella Download dell'utente in questo modo:
```
using Windows.Storage;
StorageFolder newFolder = await DownloadsFolder.CreateFolderAsync("New Folder");
```
```
Windows::Storage::StorageFolder newFolder{
    co_await Windows::Storage::DownloadsFolder::CreateFolderAsync(L"New Folder")
};
// Process folder
```
DownloadsFolder. CreateFolderAsync è sottoposto a overload in modo da poter specificare le operazioni che il sistema deve eseguire se è già presente una sottocartella esistente nella cartella Download con lo stesso nome. Al termine di questi metodi, restituiscono un oggetto StorageFolder che rappresenta la sottocartella creata. Questo file viene chiamato newFolder nell'esempio.

Accesso a posizioni aggiuntive

Oltre ai percorsi predefiniti, un'app può accedere ad altri file e cartelle dichiarando le funzionalità nel manifesto dell'app o chiamando una selezione file per consentire all'utente di selezionare file e cartelle per l'accesso all'app.

Le app che dichiarano l'estensione AppExecutionAlias dispongono delle autorizzazioni del file system dalla directory da cui vengono avviate nella finestra della console e verso il basso.

Conservazione dell'accesso a file e cartelle

Quando l'app recupera un file o una cartella tramite una selezione, un'attivazione di file, un'operazione di trascinamento della selezione e così via, ha accesso solo a tale file o cartella finché l'app non viene terminata. Se vuoi accedere automaticamente al file o alla cartella in futuro, puoi aggiungerlo a FutureAccessList in modo che l'app possa accedere facilmente a tale elemento in futuro. È anche possibile usare MostRecentlyUsedList per gestire facilmente un elenco di file usati di recente.

Funzionalità per l'accesso ad altre posizioni

La tabella seguente elenca i percorsi aggiuntivi a cui è possibile accedere dichiarando una o più funzionalità e usando l'API Windows.Storage associata.

Ubicazione	Capability	Windows.Storage API
Tutti i file a cui l'utente ha accesso. Ad esempio: documenti, immagini, foto, download, desktop, OneDrive e così via.	broadFileSystemAccess Si tratta di una funzionalità con restrizioni. L'accesso è configurabile in impostazioni > privacy >file system. Poiché gli utenti possono concedere o rifiutare l'autorizzazione in qualsiasi momento in Impostazioni, è necessario assicurarsi che l'app sia resiliente a tali modifiche. Se si scopre che l'app non ha accesso, è possibile scegliere di richiedere all'utente di modificare l'impostazione fornendo un collegamento all'articolo accesso e privacy del file system di Windows . Si noti che l'utente deve chiudere l'app, attivare o disattivare l'impostazione e riavviare l'app. Se attivano o disattivano l'impostazione mentre l'app è in esecuzione, la piattaforma sospende l'app in modo da poter salvare lo stato, quindi termina forzatamente l'app per applicare la nuova impostazione. Nell'aggiornamento di aprile 2018, l'impostazione predefinita per l'autorizzazione è attiva. Nell'aggiornamento di ottobre 2018, l'impostazione predefinita è disattivata. Se invii un'app allo Store che dichiara questa funzionalità, dovrai fornire descrizioni aggiuntive del motivo per cui la tua app necessita di questa funzionalità e come intende usarla. Questa funzionalità funziona per le API nello spazio dei nomi Windows.Storage . Vedere la sezione Esempio alla fine di questo articolo per un esempio di come abilitare questa funzionalità nell'app. Nota: questa funzionalità non è supportata in Xbox.	Non disponibile
Documents	libreriaDocumenti Nota: devi aggiungere associazioni di tipi di file al manifesto dell'app che dichiarano tipi di file specifici a cui l'app può accedere in questo percorso. Usare questa funzionalità se l'app: - Facilita l'accesso offline multipiattaforma a contenuti specifici di OneDrive usando URL di OneDrive o ID risorsa validi - Salva automaticamente i file aperti in OneDrive dell'utente mentre è offline	KnownFolders.DocumentsLibrary
Music	libreria musicale Vedi anche File e cartelle nelle raccolte Musica, Immagini e Video.	KnownFolders.MusicLibrary
Pictures	libreria di immagini Vedi anche File e cartelle nelle raccolte Musica, Immagini e Video.	KnownFolders.PicturesLibrary
Video	LibreriaVideo Vedi anche File e cartelle nelle raccolte Musica, Immagini e Video.	KnownFolders.VideosLibrary
Dispositivi rimovibili	archiviazione rimovibile Nota Devi aggiungere associazioni di tipi di file al manifesto dell'app che dichiarano tipi di file specifici a cui l'app può accedere in questo percorso. Vedere anche Accedere alla scheda SD.	KnownFolders.RemovableDevices
Librerie del Gruppo Home	È necessaria almeno una delle funzionalità seguenti. - musicLibrary - libreria di immagini - libreria video	KnownFolders.HomeGroup
Dispositivi server multimediali (DLNA)	È necessaria almeno una delle funzionalità seguenti. - musicLibrary - libreria immagini - libreriaVideo	KnownFolders.MediaServerDevices
Cartelle UNC (Universal Naming Convention)	È necessaria una combinazione delle funzionalità seguenti. Funzionalità delle reti domestico e aziendale: - privateNetworkClientServer E almeno una funzionalità di rete Internet e pubblica: - InternetClient - internetClientServer Inoltre, se applicabile, la funzionalità delle credenziali di dominio: - enterpriseAuthentication Nota: Devi aggiungere associazioni di tipi di file al manifesto dell'app che dichiarano tipi di file specifici a cui l'app può accedere in questo percorso.	Recuperare una cartella usando: StorageFolder.GetFolderFromPathAsync Recuperare un file usando: StorageFile.GetFileFromPathAsync

Esempio

In questo esempio viene aggiunta la funzionalità broadFileSystemAccess con restrizioni. Oltre a specificare la funzionalità, il namespace rescap deve essere aggiunto ed è anche inserito in IgnorableNamespaces.

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

Annotazioni

Per un elenco completo delle funzionalità delle app, vedi Dichiarazioni di funzionalità delle app.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-03-31