Guia de início rápido: dados de aplicativo em roaming (HTML)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Saiba como armazenar e recuperar configurações e arquivos do repositório de dados de aplicativo em roaming. Para informações sobre o repositório de dados de aplicativo em roaming e porque você deve usá-lo, consulte Dados de aplicativo em roaming.

Registrar-se para receber notificação quando da alteração de dados móveis

Este exemplo define datachangeHandler como o manipulador nas alterações de dados móveis.


var applicationData = Windows.Storage.ApplicationData.current;
 
function initialize() 
{
    applicationData.addEventListener("datachanged", datachangeHandler);
}

function dataChangeHandler(eventArgs)
{
    // TODO: Refresh your data
}

Obter os contêineres para as configurações e arquivos do aplicativo

Use a propriedade ApplicationData.roamingSettings para obter as configurações e a propriedade ApplicationData.roamingFolder para obter os arquivos.

var roamingSettings = applicationData.roamingSettings;
var roamingFolder = applicationData.roamingFolder;

As próximas etapas usam as variáveis roamingSettings e roamingFolder a partir dessa etapa.

Gravar dados para uma configuração

Use a propriedade ApplicationDataContainer.values para acessar as configurações no contêiner roamingSettings que obtivemos na etapa anterior. Este exemplo cria uma configuração chamada exampleSetting e uma configuração HighPriority que é melhor indicada para informações transicionais de tempo crítico, como o estado do aplicativo.

// Simple setting

roamingSettings.values["exampleSetting"] = "Hello World";
// High Priority setting, for example, last page position in book reader app

roamingSettings.values["HighPriority"] = "65";

Um objeto ApplicationDataCompositeValue contém as configurações que devem ser acessadas automaticamente. Este exemplo cria uma definição composta nomeada exampleCompositeSetting e a adiciona ao contêiner roamingSettings.

// Composite setting

var composite = new Windows.Storage.ApplicationDataCompositeValue();
composite["intVal"] = 1;
composite["strVal"] = "string";

roamingSettings.values["exampleCompositeSetting"] = composite;

Chame o método ApplicationDataContainer.CreateContainer para criar um contêiner de configurações. Este exemplo cria um contêiner nomeado exampleContainer e adiciona uma configuração nomeada exampleSetting. O valor Always da enumeração de ApplicationDataCreateDisposition indica que o contêiner deve ser criado se ele já não existir.

Após alterar uma configuração no repositório de dados de aplicativo de roaming, o sistema operacional envia o evento datachanged.

// Setting in a container

var container = roamingSettings.createContainer("exampleContainer", 
                                                Windows.Storage.ApplicationDataCreateDisposition.Always);

if (roamingSettings.containers.hasKey("exampleContainer"))
{
    roamingSettings.containers.lookup("exampleContainer").values["exampleSetting"] = "Hello World";
}

Ler dados de uma configuração

Use a propriedade ApplicationDataContainer.values para acessar a configuração exampleSetting no contêiner roamingSettings.

// Simple setting

var value = roamingSettings.values["exampleSetting"];
        
if (!value)
{
    // No data
}
else
{
    // Access data in value
}

Use a propriedade ApplicationDataContainer.values para acessar a configuração exampleCompositeSetting no contêiner roamingSettings.

// Composite setting

var composite = roamingSettings.values["exampleCompositeSetting"];

if (!composite)
{
    // No data
}
else
{
    // Access data in composite["intVal"] and composite["strVal"]
}

Use a propriedade ApplicationDataContainer.values para acessar a configuração exampleSetting no contêiner exampleContainer.

// Setting in a container

var hasContainer = roamingSettings.containers.hasKey("exampleContainer");

if (hasContainer)
{
    // Access data in roamingSettings.containers.lookup("exampleContainer").values.hasKey("exampleSetting");
}

Gravar dados em um arquivo

Use as APIs de arquivo, como Windows.Storage.StorageFolder.createFileAsync e Windows.Storage.FileIO.writeTextAsync, para criar e atualizar um arquivo no armazenamento de dados do aplicativo local. Este exemplo cria um arquivo chamado dataFile.txt no contêiner roamingFolder e escreve a data e hora atual no arquivo. O valor replaceExisting da enumeração CreationCollisionOption indica para substituir o arquivo se ele já existir.

function writeTimestamp() {
   roamingFolder.createFileAsync("dataFile.txt", Windows.Storage.CreationCollisionOption.replaceExisting)
      .then(function (sampleFile) {
         var formatter = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("longtime");
         var timestamp = formatter.format(new Date());

         return Windows.Storage.FileIO.writeTextAsync(sampleFile, timestamp);
      }).done(function () {      
      });
}

Ler dados de um arquivo

Use as APIs de arquivo, como Windows.Storage.StorageFolder.getFileAsync, Windows.Storage.StorageFile.GetFileFromApplicationUriAsync e Windows.Storage.FileIO.readTextAsync, para abrir e ler um arquivo no repositório de dados de aplicativo de roaming. Este exemplo abre o arquivo dataFile.txt criado na etapa anterior e lê a data do arquivo. O valor openIfExists da enumeração CreationCollisionOption indica que o arquivo deve existir. Para saber detalhes de como carregar recursos de arquivos de vários locais, veja Como carregar recursos de arquivos.

function readTimestamp() {
   roamingFolder.getFileAsync("dataFile.txt")
      .then(function (sampleFile) {
         return Windows.Storage.FileIO.readTextAsync(sampleFile);
      }).done(function (timestamp) {
         // Data is contained in timestamp
      }, function () {
         // Timestamp not found
      });
}

Excluir as configurações quando já não forem necessárias

Chame o método ApplicationDataContainerSettings.remove para excluir a configuração exampleSetting do contêiner roamingSettings ao concluí-la.

// Simple setting

roamingSettings.values.remove("exampleSetting");

Chame o método ApplicationDataCompositeValue.remove para excluir a configuração da composição exampleCompositeSetting do contêiner roamingSettings ao concluí-la.

// Delete composite setting

roamingSettings.values.remove("exampleCompositeSetting");

Chame o método ApplicationDataContainer.deleteContainer para excluir o contêiner de configurações exampleContainer ao concluí-lo.

// Delete container

roamingSettings.deleteContainer("exampleContainer");

Comentários

Cada aplicativo tem uma cota para os dados do aplicativo em roaming. Verifique a propriedade ApplicationData.roamingStorageQuota para determinar o tamanho total permitido para os dados de roaming. Se os dados de roaming ultrapassarem a cota, o roaming não será efetuado até que o tamanho dos dados seja novamente inferior à cota.