ApplicationData Classe

Définition

Espace de noms:

Windows.Storage

Fournit l’accès au magasin de données d’application. Les données d’application se composent de fichiers et de paramètres locaux, itinérants ou temporaires.

public ref class ApplicationData sealed : IClosable

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
class ApplicationData final : IClosable

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.MTA)]
public sealed class ApplicationData : System.IDisposable

Public NotInheritable Class ApplicationData
Implements IDisposable

Héritage

Object Platform::Object IInspectable ApplicationData

Attributs

ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implémente

IClosable IDisposable

Configuration requise pour Windows

Famille d’appareils	Windows 10 (introduit dans 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduit dans v1.0)

Exemples

L’exemple de code suivant montre comment lire ou écrire dans un dossier ApplicationData de votre choix. Cet exemple utilise localFolder, mais le code peut être légèrement modifié pour accéder à LocalCacheFolder, RoamingFolder, SharedLocalFolder ou TemporaryFolder en fonction de la façon dont vos données doivent être stockées. SharedLocalFolder a certaines restrictions et nécessite des autorisations spéciales pour y accéder, pour plus d’informations, consultez SharedLocalFolder.

// This example code can be used to read or write to an ApplicationData folder of your choice.

// Change this to Windows.Storage.StorageFolder roamingFolder = Windows.Storage.ApplicationData.Current.RoamingFolder;
// to use the RoamingFolder instead, for example.
Windows.Storage.StorageFolder localFolder = Windows.Storage.ApplicationData.Current.LocalFolder;

// Write data to a file
async void WriteTimestamp()
{
   Windows.Globalization.DateTimeFormatting.DateTimeFormatter formatter = 
       new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("longtime");

   StorageFile sampleFile = await localFolder.CreateFileAsync("dataFile.txt", 
       CreationCollisionOption.ReplaceExisting);
   await FileIO.WriteTextAsync(sampleFile, formatter.Format(DateTime.Now));
}

// Read data from a file
async Task ReadTimestamp()
{
    try
    {
        StorageFile sampleFile = await localFolder.GetFileAsync("dataFile.txt");
        String timestamp = await FileIO.ReadTextAsync(sampleFile);
        // Data is contained in timestamp
    }
    catch (FileNotFoundException e)
    {
        // Cannot find file
    }
    catch (IOException e)
    {
        // Get information from the exception, then throw
        // the info to the parent method.
        if(e.Source != null)
        {
            Debug.WriteLine("IOException source: {0}", e.Source);
        }
        throw;
    }
}

#include <winrt/Windows.Globalization.h>
#include <winrt/Windows.Globalization.DateTimeFormatting.h>
#include <winrt/Windows.Storage.h>

using namespace winrt;
using namespace Windows::Foundation;
using namespace Windows::Storage;
using namespace Windows::UI::Xaml;

// This example code can be used to read or write to an ApplicationData folder of your choice.

// Change this to StorageFolder m_localFolder{ Windows::Storage::ApplicationData::Current().RoamingFolder() }; to 
// use the RoamingFolder instead, for example.
StorageFolder m_localFolder{ Windows::Storage::ApplicationData::Current().LocalFolder() };

// Write data to a file.
IAsyncAction MainPage::WriteTimestampAsync()
{
    StorageFile sampleFile{ co_await m_localFolder.CreateFileAsync(L"dataFile.txt", CreationCollisionOption::ReplaceExisting) };
    Windows::Globalization::Calendar calendar;
    auto now = calendar.GetDateTime();
    Windows::Globalization::DateTimeFormatting::DateTimeFormatter formatter{ L"longtime" };

    try
    {
        co_await FileIO::WriteTextAsync(sampleFile, formatter.Format(now));
    }
    catch (winrt::hresult_error const& /* ex */)
    {
        // Timestamp not written.
    }
}

// Read data from a file.
IAsyncAction MainPage::ReadTimestampAsync()
{
    StorageFile file{ co_await m_localFolder.GetFileAsync(L"dataFile.txt") };

    try
    {
        winrt::hstring timestamp{ co_await Windows::Storage::FileIO::ReadTextAsync(file) };
    }
    catch (winrt::hresult_error const& /* ex */)
    {
        // Timestamp not read.
    }
}

IAsyncAction MainPage::ClickHandler(IInspectable const&, RoutedEventArgs const&)
{
    myButton().Content(box_value(L"Clicked"));

    co_await WriteTimestampAsync();
    co_await ReadTimestampAsync();
}

// This example code can be used to read or write to an ApplicationData folder of your choice.

// Change this to StorageFolder^ roamingFolder = ApplicationData::Current->RoamingFolder; to 
// use the RoamingFolder instead, for example.
StorageFolder^ localFolder = ApplicationData::Current->LocalFolder;

// Write data to a file
void MainPage::WriteTimestamp()
{
   concurrency::task<StorageFile^> fileOperation = 
       localFolder->CreateFileAsync("dataFile.txt", CreationCollisionOption::ReplaceExisting);
   fileOperation.then([this](StorageFile^ sampleFile)
   {
      auto calendar = ref new Calendar;
      auto now = calendar->ToDateTime();
      auto formatter = ref new Windows::Globalization::DateTimeFormatting::DateTimeFormatter("longtime");

      return FileIO::WriteTextAsync(sampleFile, formatter->Format(now));
   }).then([this](task<void> previousOperation) {
      try {
         previousOperation.get();
      } catch (Platform::Exception^) {
         // Timestamp not written
      }
   });
}

// Read data from a file
void MainPage::ReadTimestamp()
{
   concurrency::task<StorageFile^> getFileOperation(localFolder->GetFileAsync("dataFile.txt"));
   getFileOperation.then([this](StorageFile^ file)
   {
      return FileIO::ReadTextAsync(file);
   }).then([this](concurrency::task<String^> previousOperation) {
      String^ timestamp;

      try {
         // Data is contained in timestamp
         timestamp = previousOperation.get();
      } catch (...) {
         // Timestamp not found
      }
   });
}

' This example code can be used to read or write to an ApplicationData folder of your choice.

' Change this to Dim roamingFolder As Windows.Storage.StorageFolder = Windows.Storage.ApplicationData.Current.RoamingFolder
' to use the RoamingFolder instead, for example.
Dim localFolder As Windows.Storage.StorageFolder = Windows.Storage.ApplicationData.Current.LocalFolder

' Write data to a file
Private Async Sub WriteTimestamp()
   Dim formatter As DateTimeFormatter = New DateTimeFormatter("longtime")

   Dim sampleFile As StorageFile = Await localFolder.CreateFileAsync("dataFile.txt", 
       CreationCollisionOption.ReplaceExisting)
   Await FileIO.WriteTextAsync(sampleFile, formatter.Format(DateTime.Now));
End Sub

' Read data from a file
Private Async Function ReadTimestamp() As Task
   Try
      Dim sampleFile As StorageFile = Await localFolder.GetFileAsync("dataFile.txt")
      Dim timestamp As string = Await FileIO.ReadTextAsync(sampleFile)
      ' Data is contained in timestamp
   Catch e1 As Exception
      ' Timestamp not found
   End Try
End Function

Pour plus d’exemples et d’informations sur la lecture et l’écriture dans un fichier, consultez Créer, écrire et lire un fichier.

Remarques

Types de données d’application

ApplicationData fournit un stockage local, itinérant et temporaire pour les données d’application par utilisateur. Utilisez cette classe pour conserver des données spécifiques à l’application entre les sessions, les utilisateurs et sur plusieurs appareils.

ApplicationData ne fournit pas l’accès aux fichiers dans un package d’application. Pour ce faire, utilisez Windows.ApplicationModel.Package.InstalledLocation.

ApplicationData.Current vous donne l’instance ApplicationData de l’application. Utilisez cette instance pour obtenir des dossiers ou des paramètres d’application.

Les dossiers sont utilisés pour stocker les données d’application sous forme de fichiers sur le système de fichiers. Les paramètres d’application sont stockés dans des paires clé/valeur qui peuvent être organisées dans des ensembles imbriqués. Les données de paramètres sont enregistrées dans le Registre Windows.

Voici les main types de données d’application :

• Local : stocké sur l’appareil, sauvegardé dans le cloud et persistant entre les mises à jour
• LocalCache : données persistantes qui existent sur l’appareil actuel, qui ne sont pas sauvegardées et qui persistent entre les mises à jour
• SharedLocal : persistant pour tous les utilisateurs de l’application
• Itinérance : existe sur tous les appareils sur lesquels l’utilisateur a installé l’application
• Temporaire : peut être supprimé par le système à tout moment

Utilisation des dossiers d’application

LocalFolder persiste entre les mises à jour et est sauvegardé dans le cloud dans le cadre de la sauvegarde de l’appareil. En règle générale, ce dossier doit être utilisé pour les données utilisateur qui seraient perdues si elles n’étaient pas sauvegardées. Voici quelques exemples de données stockées dans LocalFolder :

• un dessin utilisateur pour une application d’art
• historique quotidien des exercices pour une application de remise en forme
• une liste d’achats pour une application todo En stockant des informations dans localFolder, l’utilisateur ne perd pas de données après avoir réinitialisé l’appareil ou basculé vers un nouvel appareil. Pour d’autres types de données locales qui sont faciles à recréer et qui ne sont pas nécessaires pour la sauvegarde et la restauration, utilisez localCacheFolder ou TemporaryFolder.

LocalCacheFolder et TemporaryFolder sont stockés localement et ne sont pas sauvegardés dans le cloud. LocalCacheFolder est sous contrôle de cette application et est persistant entre les sessions d’application. LocalCacheFolder doit être utilisé pour le contenu généré nécessaire entre les sessions d’application, tels que les fichiers mis en cache, les journaux ou les jetons d’authentification. TemporaryFolder n’est pas garanti pour être persistant entre les sessions et peut être supprimé par le système à tout moment.

RoamingFolder est généralement utilisé pour les préférences utilisateur et les personnalisations, les liens et les petits fichiers de données. Le contenu de RoamingFolder est itinérant sur les appareils et instances d’application de l’utilisateur. RoamingFolder ne doit pas être utilisé pour de grandes quantités de données, des données spécifiques à un appareil ou des données qui reposent sur la synchronisation instantanée.

Un autre dossier, SharedLocalFolder, est persistant entre les comptes d’utilisateur d’application et doit être utilisé pour les fichiers volumineux auxquels plusieurs utilisateurs accèdent. Une configuration supplémentaire est requise pour accéder à SharedLocalFolder. Pour plus d’informations sur l’accès et l’utilisation de ce dossier, consultez SharedLocalFolder.

Vous pouvez stocker vos données d’application dans des formats de version spécifiques à l’application. Pour plus d’informations, consultez Version et SetVersionAsync.

Pour plus d’informations sur l’utilisation de ces API, consultez Stocker et récupérer des paramètres et d’autres données d’application.

Propriétés

Current	Fournit l’accès au magasin de données d’application associé au package d’application de l’application.
LocalCacheFolder	Obtient le dossier dans le magasin de données d’application local où vous pouvez enregistrer des fichiers qui ne sont pas inclus dans la sauvegarde et la restauration.
LocalFolder	Obtient le dossier racine dans le magasin de données d’application local. Ce dossier est sauvegardé dans le cloud.
LocalSettings	Obtient le conteneur de paramètres d’application dans le magasin de données d’application local.
RoamingFolder	Obtient le dossier racine dans le magasin de données d’application itinérant.
RoamingSettings	Obtient le conteneur de paramètres d’application dans le magasin de données d’application itinérant.
RoamingStorageQuota	Obtient la taille maximale des données qui peuvent être synchronisées avec le cloud à partir du magasin de données d’application itinérante.
SharedLocalFolder	Obtient le dossier racine dans le magasin de données d’application partagé.
TemporaryFolder	Obtient le dossier racine dans le magasin de données d’application temporaire.
Version	Obtient le numéro de version des données d’application dans le magasin de données d’application.

Méthodes

ClearAsync()	Supprime toutes les données d’application des magasins de données d’application locaux, itinérants et temporaires. Notes La méthode ClearAsync() rencontre une erreur s’il existe des handles de fichier ouverts. Veillez à fermer tous les fichiers ouverts avant d’appeler ClearAsync.
ClearAsync(ApplicationDataLocality)	Supprime toutes les données d’application du magasin de données d’application spécifié. Notes La méthode ClearAsync(ApplicationDataLocality) rencontre une erreur s’il existe des handles de fichier ouverts. Veillez à fermer tous les fichiers ouverts avant d’appeler ClearAsync.
ClearPublisherCacheFolderAsync(String)	Efface les fichiers et sous-dossiers du sous-dossier spécifié du dossier de stockage partagé pour l’éditeur de l’application actuelle.
Close()	Notes Ce membre n’est pas implémenté en C#.
Dispose()	Exécute les tâches définies par l'application associées à la libération ou à la redéfinition des ressources non managées.
GetForUserAsync(User)	Méthode statique qui retourne applicationData pour un utilisateur.
GetPublisherCacheFolder(String)	Obtient le sous-dossier spécifié du dossier de stockage partagé pour l’éditeur de l’application actuelle.
SetVersionAsync(UInt32, ApplicationDataSetVersionHandler)	Définit le numéro de version des données d’application dans le magasin de données d’application.
SignalDataChanged()	Envoie un événement DataChanged à tous les gestionnaires d’événements inscrits.

Événements

DataChanged

Se produit lorsque les données d’application itinérantes sont synchronisées.

Voir aussi

• ApplicationDataCompositeValue
• ApplicationDataContainer
• ApplicationDataContainerSettings
• Stocker et récupérer des paramètres et autres données d’application
• Recommandations en matière de données d’application itinérantes
• Recommandations en matière de paramètres de l’application
• Exemple de paramètres d’application (Windows 8.1, Windows Phone 8.1)
• Exemple de données d’application