Usare i file

  • Articolo

Questo argomento illustra i concetti necessari per iniziare a leggere e scrivere nei file in un'app UWP (Universal Windows Platform). Introduce le API e i tipi principali e fornisce collegamenti ad altre informazioni.

Non si tratta di un'esercitazione. Per un'esercitazione, vedi Creare, scrivere e leggere un file che, oltre a illustrare come creare, leggere e scrivere un file, mostra anche come usare buffer e flussi. Potrebbe anche interessarti l'esempio di accesso a file, che mostra come creare, leggere, scrivere, copiare ed eliminare un file, nonché come recuperare le proprietà dei file e memorizzare un file o una cartella in modo che l'app possa accedervi di nuovo facilmente.

Esamineremo il codice per la scrittura e la lettura di testo da un file e vedremo come accedere alle cartelle locali, di roaming e temporanee dell'app.

Cosa sapere

Ecco i tipi principali da conoscere per leggere o scrivere testo da o in un file:

  • Windows.Storage.StorageFile rappresenta un file. Questa classe ha proprietà che forniscono informazioni sui file e metodi di creazione, apertura, copia, eliminazione e ridenominazione dei file. Probabilmente conosci già l'uso dei percorsi stringa. Alcune API di Windows Runtime accettano un percorso stringa, ma in generale si usa StorageFile per rappresentare un file, perché alcuni file usati nella piattaforma UWP potrebbero non avere un percorso o avere un percorso difficile da gestire. Usa StorageFile.GetFileFromPathAsync() per convertire un percorso stringa in StorageFile.

  • La classe FileIO offre un modo semplice per leggere e scrivere testo. Questa classe può anche leggere/scrivere una matrice di byte o il contenuto di un buffer. È molto simile alla classe PathIO. La differenza principale è che, anziché usare un percorso stringa come in PathIO, usa StorageFile.

  • Windows.Storage.StorageFolder rappresenta una cartella (directory). Questa classe include metodi per la creazione di file, l'esecuzione di query sul contenuto di una cartella, la creazione, la ridenominazione e l'eliminazione di cartelle, oltre a proprietà che forniscono informazioni su una cartella.

I modi più comuni per ottenere una classe StorageFolder includono:

Scrivere testo in un file

Per questa introduzione ci concentreremo su uno scenario semplice: la lettura e la scrittura di testo. Iniziamo esaminando codice che usa la classe FileIO per scrivere testo in un file.

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.

Vediamo prima di tutto dove si trova il file. Windows.Storage.ApplicationData.Current.LocalFolder permette di accedere alla cartella di dati locale, che viene creata per l'app al momento dell'installazione. Per informazioni dettagliate sulle cartelle a cui l'app può accedere, vedi Accedere al file system.

Usiamo quindi StorageFolder per creare il file o per aprirlo se esiste già.

La classe FileIO offre un modo pratico per scrivere testo nel file. FileIO.WriteTextAsync() sostituisce l'intero contenuto del file con il testo specificato. FileIO.AppendLinesAsync() aggiunge una raccolta di stringhe al file, scrivendo una stringa per ogni riga.

Leggere testo da un file

Come per la scrittura di un file, la lettura di un file inizia specificandone il percorso. Useremo lo stesso percorso dell'esempio precedente. Quindi useremo la classe FileIO per leggerne il contenuto.

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

Puoi anche leggere ogni riga del file in stringhe singole in una raccolta usando IList<string> contents = await Windows.Storage.FileIO.ReadLinesAsync(sampleFile);

Accedere al file system

Nella piattaforma UWP, l'accesso alle cartelle è limitato per garantire l'integrità e la privacy dei dati dell'utente.

Cartelle dell'app

Quando viene installata un'app piattaforma UWP, vengono create varie cartelle in c:\utenti<nome utente>\AppData\Local\Packages<identificatore pacchetto dell'app>\ per archiviare, tra l'altro, i file temporanei, di roaming e locali dell'app. L'app non deve necessariamente dichiarare funzionalità per accedere a tali cartelle, che non sono accessibili da altre app. Quando l'app viene disinstallata, vengono rimosse anche le cartelle.

Ecco alcune delle cartelle dell'app di uso comune:

  • LocalState: per i dati locali del dispositivo corrente. Quando viene eseguito il backup del dispositivo, i dati in questa directory vengono salvati in un'immagine di backup in OneDrive. Se l'utente ripristina o sostituisce il dispositivo, vengono ripristinati anche i dati. Accedi a questa cartella con Windows.Storage.ApplicationData.Current.LocalFolder. Salva i dati locali di cui non vuoi eseguire il backup in OneDrive in LocalCacheFolder, a cui puoi accedere con Windows.Storage.ApplicationData.Current.LocalCacheFolder.

  • RoamingState: no viene più effettuato il roaming dei dati archiviati qui (nell'ambito di Windows 11), ma la cartella è ancora disponibile. Accedi alla cartella di roaming con Windows.Storage.ApplicationData.Current.RoamingFolder. La sostituzione consigliata è Servizio app di Azure. Servizio app di Azure è ampiamente supportato, ben documentato, affidabile e supporta scenari multi-piattaforma e multi-ambiente, come iOS, Android e Web.

  • TempState: per i dati che possono essere eliminati quando l'app non è in esecuzione. Accedi a questa cartella con Windows.Storage.ApplicationData.Current.TemporaryFolder.

Accedere al resto del file system

Un'app UWP deve dichiarare l'intento di accedere a una raccolta utente specifica aggiungendo la funzionalità corrispondente al manifesto. Al momento dell'installazione dell'app, all'utente viene quindi richiesto di assicurarsi di autorizzare l'accesso alla raccolta specificata. In caso contrario, l'app non verrà installata. Sono disponibili funzionalità per accedere alle raccolte musicali, di immagini e di video. Per un elenco completo, vedi Dichiarazioni di funzionalità delle app. Per ottenere un oggetto StorageFolder per queste raccolte, usa la classe Windows.Storage.KnownFolders.

Raccolta documenti

Anche se è disponibile una funzionalità per l'accesso alla raccolta documenti dell'utente, tale funzionalità è limitata. Ciò significa che un'app che la dichiara viene rifiutata da Microsoft Store, a meno che non venga seguita una procedura per ottenere un'approvazione speciale. Non è ideata per l'uso generico. Usa invece le selezioni file o cartelle (vedi Aprire file e cartelle con una selezione e Salvare un file con una selezione), che permettono all'utente di passare alla cartella o al file. Quando l'utente passa a una cartella o a un file, concede in modo implicito all'app l'autorizzazione all'accesso e il sistema permette l'accesso.

Accesso generale

In alternativa, l'app può dichiarare la funzionalità broadFileSystem con restrizioni nel manifesto. Anche questa opzione richiede l'approvazione di Microsoft Store. L'app può quindi accedere a qualsiasi file a cui l'utente ha accesso, senza richiedere l'intervento di una selezione file o cartelle.

Per un elenco completo dei percorsi a cui le app possono accedere, vedi Autorizzazioni di accesso ai file.

API e documentazione utili

Ecco un breve riepilogo delle API e di altra documentazione utili per aiutarti a iniziare a usare i file e le cartelle.

API utili

API Descrizione
Windows.Storage.StorageFile Fornisce informazioni sul file e metodi di creazione, apertura, copia, eliminazione e ridenominazione dei file.
Windows.Storage.StorageFolder Fornisce informazioni sulla cartella, metodi di creazione dei file e metodi di creazione ridenominazione ed eliminazione delle cartelle.
FileIO Offre un modo semplice per leggere e scrivere testo. Questa classe può anche leggere/scrivere una matrice di byte o il contenuto di un buffer.
PathIO Offre un modo semplice per leggere/scrivere testo da o in un file a partire da un percorso stringa per il file. Questa classe può anche leggere/scrivere una matrice di byte o il contenuto di un buffer.
DataReader & DataWriter Permette di leggere e scrivere buffer, byte, Integer, GUID, TimeSpan e altro da o in un flusso.
Windows.Storage.ApplicationData.Current Offre accesso alle cartelle create per l'app, ad esempio la cartella locale, la cartella di roaming e la cartella dei file temporanei.
Windows.Storage.Pickers.FolderPicker Permette all'utente di scegliere una cartella, per la quale restituisce StorageFolder. In questo modo puoi accedere a percorsi a cui l'app non può accedere per impostazione predefinita.
Windows.Storage.Pickers.FileOpenPicker Permette all'utente di scegliere un file da aprire, per il quale restituisce StorageFile. In questo modo puoi accedere a file a cui l'app non può accedere per impostazione predefinita.
Windows.Storage.Pickers.FileSavePicker Permette all'utente di scegliere il nome del file, l'estensione e la posizione di archiviazione per un file. Restituisce un oggetto StorageFile. In questo modo puoi salvare file in percorsi a cui l'app non può accedere per impostazione predefinita.
Spazio dei nomi Windows.Storage.Streams Fornisce il supporto per la lettura e la scrittura di flussi. Vedi in particolare le classi DataReader e DataWriter, che permettono di leggere e scrivere buffer, byte, Integer, GUID, TimeSpan e altro.

Documentazione utile

Argomento Descrizione
Spazio dei nomi Windows.Storage Documentazione di riferimento per le API.
File, cartelle e raccolte Documentazione concettuale.
Creare, scrivere e leggere un file Illustra come creare, leggere e scrivere testo, dati binari e flussi.
Introduzione all'archiviazione locale dei dati dell'app Oltre alle procedure consigliate per il salvataggio dei dati locali, illustra lo scopo delle cartelle LocalSettings e LocalCache.
Archiviare e recuperare le impostazioni e altri dati dell'app Offre una panoramica dei vari archivi dati dell'app, ad esempio le cartelle locali, di roaming e temporanee.
Autorizzazioni di accesso ai file Offre informazioni sui percorsi del file system a cui l'app può accedere.
Aprire file e cartelle con una selezione Mostra come accedere a file e cartelle permettendo all'utente di decidere con un'interfaccia utente di selezione.
Windows.Storage.Streams Tipi usati per leggere e scrivere flussi.
File e cartelle nelle raccolte Musica, Immagini e Video Illustra come rimuovere cartelle dalle raccolte, ottenere l'elenco di cartelle in una raccolta e scoprire foto, musica e video archiviati.

Esempi utili di codice

Esempio di codice Descrizione
Esempio di dati applicazione Illustra come archiviare e recuperare i dati specifici di ogni utente tramite le API dei dati applicazione.
Esempio di accesso a file Illustra come creare, leggere, scrivere, copiare ed eliminare un file.
Esempio di utilità di selezione file Mostra come accedere a file e cartelle permettendo all'utente di sceglierli con un'interfaccia utente e come salvare un file in modo che l'utente possa specificare il nome, il tipo e il percorso di un file da salvare.
Esempio di JSON Mostra come codificare e decodificare oggetti, matrici, stringhe, numeri e valori booleani JavaScript Object Notation (JSON) usando lo spazio dei nomi Windows.Data.Json.
Esempi di codice aggiuntivi Scegli Files, folders, and libraries (File, cartelle e raccolte) nell'elenco a discesa delle categorie.