CachedFileUpdaterUI CachedFileUpdaterUI CachedFileUpdaterUI CachedFileUpdaterUI Class

Used to interact with the file picker if your app provides file updates through the Cached File Updater contract.

Syntax

Declaration

public sealed class CachedFileUpdaterUIpublic sealed class CachedFileUpdaterUIPublic NotInheritable Class CachedFileUpdaterUIpublic sealed class CachedFileUpdaterUI

Remarks

In JavaScript, retrieve a CachedFileUpdaterUI object using the CachedFileUpdaterUI property.

In C#, C++, and VB, retrieve a CachedFileUpdaterUI object using the CachedFileUpdaterUI property.

Examples

The File picker contracts sample demonstrates how to respond to a ActivationKind activated event.


// CachedFileUpdater activated event handler
protected override void OnCachedFileUpdaterActivated(CachedFileUpdaterActivatedEventArgs args)
{
    var CachedFileUpdaterPage = new SDKTemplate.CachedFileUpdaterPage();
    CachedFileUpdaterPage.Activate(args);
}

// Overloaded method to respond to CachedFileUpdater events
public void Activate(CachedFileUpdaterActivatedEventArgs args)
{
            // Get file picker UI
            cachedFileUpdaterUI = args.CachedFileUpdaterUI;

            cachedFileUpdaterUI.FileUpdateRequested += CachedFileUpdaterUI_FileUpdateRequested;
            cachedFileUpdaterUI.UIRequested += CachedFileUpdaterUI_UIRequested;

            switch (cachedFileUpdaterUI.UpdateTarget)
            {
                case CachedFileTarget.Local:
                    scenarios = new List<Scenario> { new Scenario() { Title = "Get latest version", ClassType = typeof(FilePickerContracts.CachedFileUpdater_Local) } };
                    break;
                case CachedFileTarget.Remote:
                    scenarios = new List<Scenario> { new Scenario() { Title = "Remote file update", ClassType = typeof(FilePickerContracts.CachedFileUpdater_Remote) } };
                    break;
            }

            Window.Current.Activate();
        }

// cachedFileUpdater activated event handler
function activated(eventObject) {
        // Identify whether app was launched for cachedFileUpdater
        if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.cachedFileUpdater) {
            // Perform tasks to prepare your app to display its file picker page

            // Get file picker UI
            cachedFileUpdaterUI = eventObject.detail.cachedFileUpdaterUI;

            cachedFileUpdaterUI.addEventListener("fileupdaterequested", onFileUpdateRequest);
            cachedFileUpdaterUI.addEventListener("uirequested", onUIRequested);

            switch (cachedFileUpdaterUI.updateTarget) {
                case Windows.Storage.Provider.CachedFileTarget.local:
                    scenarios = [{ url: "/html/cachedFileUpdaterScenario1.html", title: "Get latest version" }];
                    break;
                case Windows.Storage.Provider.CachedFileTarget.remote:
                    scenarios = [{ url: "/html/cachedFileUpdaterScenario2.html", title: "Remote file update" }];
                    break;
            }
            SdkSample.scenarios = scenarios;
        }
    }

// Register the activated event handler
WinJS.Application.addEventListener("activated", activated, false);

For JavaScript, eventObject contains a WebUICachedFileUpdaterActivatedEventArgs object.

For C#, args contains a CachedFileUpdaterActivatedEventArgs object. Additionally, the OnCachedFileUpdaterActivated is in the App.xaml.cs file and the Activate method is in the CachedFileUpdaterPage.xaml.cs file of the File picker contracts sample.

Properties summary

Gets or sets the title to display in the top-left the file picker UI. The title identifies the location or context of the app's page (which is hosted in the file picker UI) for the user.

Gets an enum value that indicates the status of the file picker UI.

Gets the file update request currently being processed by the cached file updater.

Gets a value that indicates which version of the file needs to be updated: the local version or the version in the app's repository.

Methods summary

Gets an object used to complete a file update request asynchronously.

Events summary

Fires when the Windows requests a file update. This event fires once for each requested update.

Fires when the calling app needs to display the file picker letterbox UI that is represented by the CachedFileUpdaterUI object.

A server may defer its UI initialization until it receives this event.

Properties

  • Title
    Title
    Title
    Title

    Gets or sets the title to display in the top-left the file picker UI. The title identifies the location or context of the app's page (which is hosted in the file picker UI) for the user.

    public string Title { get; set; }public string Title { get; set; }Public ReadWrite Property Title As stringpublic string Title { get; set; }

    Property Value

    • string
      string
      string
      string

      The title to display in the top-left of the file picker UI.

    Remarks

    You should update the title to indicate the current context of your app within the file picker. For example, you could set the title to "Login" if user login is required, or "Resolve conflict" if there is a file conflict.

  • UIStatus
    UIStatus
    UIStatus
    UIStatus

    Gets an enum value that indicates the status of the file picker UI.

    public UIStatus UIStatus { get; }public UIStatus UIStatus { get; }Public ReadOnly Property UIStatus As UIStatuspublic UIStatus UIStatus { get; }

    Property Value

    Remarks

    When an app providing updates has responded to all FileUpdateRequested events, this property indicates UIStatus.

    Check for the UIStatus value to determine if your providing app has responded all FileUpdateRequested events. If the UIStatus is UIStatus your app should display page (which will be hosted in the file picker) to tell the user that the updates are complete.

  • UpdateRequest
    UpdateRequest
    UpdateRequest
    UpdateRequest

    Gets the file update request currently being processed by the cached file updater.

    public FileUpdateRequest UpdateRequest { get; }public FileUpdateRequest UpdateRequest { get; }Public ReadOnly Property UpdateRequest As FileUpdateRequestpublic FileUpdateRequest UpdateRequest { get; }

    Property Value

  • UpdateTarget
    UpdateTarget
    UpdateTarget
    UpdateTarget

    Gets a value that indicates which version of the file needs to be updated: the local version or the version in the app's repository.

    public CachedFileTarget UpdateTarget { get; }public CachedFileTarget UpdateTarget { get; }Public ReadOnly Property UpdateTarget As CachedFileTargetpublic CachedFileTarget UpdateTarget { get; }

    Property Value

    Remarks

    If your app participates in the Cached File Updater contract, you should use this property to respond to FileUpdateRequested events. If this property is CachedFileTarget, your app should update the locally cached copy of the file to match the latest version of the file that is in your app's repository. Otherwise, if it's CachedFileTarget, your app should update the version of the file that is in your app's repository to match the latest, locally cached copy of the file.

    The value of this property is applies to all of the FileUpdateRequested events that fire for a single ActivationKind activation event.

Methods

Events

  • FileUpdateRequested
    FileUpdateRequested
    FileUpdateRequested
    FileUpdateRequested

    Fires when the Windows requests a file update. This event fires once for each requested update.

    public event TypedEventHandler FileUpdateRequestedpublic event TypedEventHandler FileUpdateRequestedPublic Event FileUpdateRequestedpublic event TypedEventHandler FileUpdateRequested

    Remarks

    If your app participates in the Cached File Updater contract, you must register for this event in your app's activated event handler where you check for ActivationKind. You must respond to this FileUpdateRequested event by updating the file and setting the Status of the request. Use the @Windows.Storage.Provider.CachedFileUpdaterUI.@Windows.Storage.Provider.CachedFileUpdaterUI.UpdateTarget property to determine whether your app should update the version file in its repository or the locally cached copy of the file in response to the request.

    You can access information about the requested update by using the Request property on the object that is passed to your FileUpdateRequested event handler.

    If you need user input to complete the update, set the Status to FileUpdateStatus and complete the request. If user interaction is available, another FileUpdateRequested will fire and your app can obtain user input and complete the request.

    Examples

    The File picker contracts sample demonstrates how to respond to a FileUpdateRequested event.

    
    // Event handler
    void CachedFileUpdaterUI_FileUpdateRequested(CachedFileUpdaterUI sender, FileUpdateRequestedEventArgs args)
    {
        fileUpdateRequest = args.Request;
        fileUpdateRequestDeferral = fileUpdateRequest.GetDeferral();
        switch (cachedFileUpdaterUI.UIStatus)
        {
            case UIStatus.Hidden:
                fileUpdateRequest.Status = FileUpdateStatus.UserInputNeeded;
                fileUpdateRequestDeferral.Complete();
                break;
            case UIStatus.Visible:
                break;
            case UIStatus.Unavailable:
                fileUpdateRequest.Status = FileUpdateStatus.Failed;
                fileUpdateRequestDeferral.Complete();
                break;
        }
    }
    
    // Register for the event
    cachedFileUpdaterUI.FileUpdateRequested += CachedFileUpdaterUI_FileUpdateRequested;
    
    
    // Event handler
    function onFileUpdateRequest(e) {
        fileUpdateRequest = e.request;
        fileUpdateRequestDeferral = fileUpdateRequest.getDeferral();
    
        switch (cachedFileUpdaterUI.uiStatus) {
            case Windows.Storage.Provider.UIStatus.hidden:
                fileUpdateRequest.status = Windows.Storage.Provider.FileUpdateStatus.userInputNeeded;
                fileUpdateRequestDeferral.complete();
                break;
            case Windows.Storage.Provider.UIStatus.visible:
                var url = scenarios[0].url;
                WinJS.Navigation.navigate(url, cachedFileUpdaterUI);
                break;
            case Windows.Storage.Provider.UIStatus.unavailable:
                fileUpdateRequest.status = Windows.Storage.Provider.FileUpdateStatus.failed;
                fileUpdateRequestDeferral.complete();
                break;
        }
    }
    
    // Register for the event
    cachedFileUpdaterUI.addEventListener("fileupdaterequested", onFileUpdateRequest);
    

    Both args and e (in C# and JS respectively) contain a FileUpdateRequestedEventArgs object.

  • UIRequested
    UIRequested
    UIRequested
    UIRequested

    Fires when the calling app needs to display the file picker letterbox UI that is represented by the CachedFileUpdaterUI object.

    A server may defer its UI initialization until it receives this event.

    public event TypedEventHandler UIRequestedpublic event TypedEventHandler UIRequestedPublic Event UIRequestedpublic event TypedEventHandler UIRequested

    Remarks

    The app can register to be notified when this event fires by adding an event listener to the CachedFileUpdaterUI object and declaring a handler function. If the app has registered an event handler for this event, it must respond when the event fires by initializing its UI.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute

Details

Assembly

Windows.Storage.Provider.dll