Quickstart: Using the Accounts Settings flyout pane (XAML)

  • Article

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Your app can use the app Settings flyout to display a list of accounts that are stored in the credential locker (PasswordVault) for the current user by way of new ApplicationSettings APIs. This is especially useful if your app leverages a number of user accounts to access secure content.

This topic will show you how to add the Accounts command to the app settings flyout (SettingsPane), and how to populate the Accounts setting pane (AccountsSettingsPane) that appears when that command is activated.

Prerequisites

A basic understanding of the Windows.UI.ApplicationSettings (app Settings flyout) and Windows.Security.Credentials (credential locker) is helpful.

Initialize credential locker with account data

The AccountsSettingsPane is populated using credentials stored with the credential locker for the current user. For demonstration purposes we will create a new instance of the credential locker and populate it with some temporary data that our AccountsSettingsPane can display when it's demonstrated later in the topic.

this.InitializeComponent();

var credLocker = new Windows.Security.Credentials.PasswordVault();
credLocker.Add(new Windows.Security.Credentials.PasswordCredential("doug", "user1", "password1"));
credLocker.Add(new Windows.Security.Credentials.PasswordCredential("doug", "user2", "password2"));
credLocker.Add(new Windows.Security.Credentials.PasswordCredential("ryan", "user1", "password1"));

Define Settings behavior for OnNavigated events

Next implement the callback methods, defined later, that are responsible for adding the AccountsCommand to the SettingsPane configuration, and populates the AccountsSettingsPane when this app is running.

protected override void OnNavigatedTo(NavigationEventArgs e)
{

    Windows.UI.ApplicationSettings.SettingsPane.GetForCurrentView().
        CommandsRequested += OnCommandsRequested;

    Windows.UI.ApplicationSettings.
        AccountsSettingsPane.GetForCurrentView().
        AccountCommandsRequested += OnAccountCommandsRequested;

}

And clean things up when the app is suspended or terminated.

protected override void OnNavigatedFrom(NavigationEventArgs e)
{

    Windows.UI.ApplicationSettings.SettingsPane.GetForCurrentView().
        CommandsRequested -= OnCommandsRequested;

    Windows.UI.ApplicationSettings.AccountsSettingsPane.GetForCurrentView().
        AccountCommandsRequested -= OnAccountCommandsRequested; 

}

Include the Accounts command in the app Settings flyout

To make UI navigation to the AccountsSettingsPane possible, your app will need to request the AccountsCommand for it to appear on the SettingsPane. Once in place, this command is represented on the app Settings flyout as Accounts.

protected void OnCommandsRequested(
    Windows.UI.ApplicationSettings.SettingsPane sender,
    Windows.UI.ApplicationSettings.SettingsPaneCommandsRequestedEventArgs e)
{ 
    try
    {
        // Show the “Accounts” command when the “Settings” pane is displayed
        e.Request.ApplicationCommands.Add(
            Windows.UI.ApplicationSettings.SettingsCommand.AccountsCommand); 
    }
    catch (Exception err) 
    {
        // Handle err.
    }
}

Populate the Accounts Settings pane

After clicking Accounts on the Settings flyout, users will see the Account settings pane.

In the following example, the Accounts Settings pane is populated with account data present in the credential locker (our example data from earlier), and if stored account credentials are removed elsewhere in system during the app session, the Account settings pane is updated to reflect that change.

// Populate the Accounts settings pane with credentials from the credential locker. 
// Provide the "Remove" command for each credential.
protected void OnAccountCommandsRequested(
    Windows.UI.ApplicationSettings.AccountsSettingsPane sender, 
    Windows.UI.ApplicationSettings.AccountsSettingsPaneCommandsRequestedEventArgs e)
{
    // Get the Deferral object if async operations are required.          
    var deferral = e.GetDeferral();


    // Handler for the delete credential command.    
    var credDeletedHandler = new Windows.UI.ApplicationSettings.
        CredentialCommandCredentialDeletedHandler(OnCredentialDeleted);

    // Get credentials to display in the Settings pane.
    var credLocker = new Windows.Security.Credentials.PasswordVault();
    IReadOnlyList<Windows.Security.Credentials.PasswordCredential> credentials = 
        credLocker.RetrieveAll();

    if (credentials.Count == 0)
        e.HeaderText = "No credentials found.";
    else
        e.HeaderText = "User credentials:";

    foreach (var c in credentials)
    {
        try
        {
            var credCommand = new Windows.UI.ApplicationSettings.
                CredentialCommand(c, credDeletedHandler);

            // Delete command is invoked after the system deletes the credential
            e.CredentialCommands.Add(credCommand);
        }
        catch (Exception err) 
        {
            // Handle error.
        }
    }

    // Complete the Deferral.
    deferral.Complete();
}

The Windows.UI.ApplicationSettings namespace also defines a set of classes specifically for associating commands with a WebAccount, enabling management of these accounts through the app Settings flyout.

Summary

This topic showed you how to display saved accounts for a user in the app Settings flyout. To learn how to provide a UI for credential input, store credentials locally, or authenticate with a service on the web, check out the following topics:

Windows.UI.ApplicationSettings

Windows.Security.Credentials