WorkspaceBrokerAx object

Article
07/05/2016

[WorkspaceBrokerAx is no longer available for use as of Windows 10 and Windows Server 2016 Technical Preview.]

The WorkspaceBrokerAx object allows a Windows Store app to set up and use RemoteApp and Desktop Connections workspaces.

Members

The WorkspaceBrokerAx object has these types of members:

Events
Methods
Properties

Events

The WorkspaceBrokerAx object has these events.

Event	Description
OnWorkspaceSetupCompleted	This event is fired when the SetupWorkspace method is complete.

Methods

The WorkspaceBrokerAx object has these methods.

Method	Description
InitializeWorkspaceConfiguration	Called to initialize the state of the object.
LaunchWorkspaceItem	Launches the specified workspace item.
SetupWorkspace	Invokes the system-implemented new Windows UI that allows the user to enter the email address or URL to use for the RemoteApp and Desktop Connections.

Properties

The WorkspaceBrokerAx object has these properties.

Property	Access type	Description
IsWorkspaceFolderItemRemoteDesktop	Read-only	Specifies if the folder item is a remote desktop.
WorkspaceFolderContentsCount	Read-only	Contains the number of items in the specified workspace folder.
WorkspaceFolderImageData	Read-only	Contains the display image of the specified folder item.
WorkspaceFolderItemFileExtension	Read-only	Contains the file extension of the specified folder item.
WorkspaceFolderItemName	Read-only	Contains the display name of the specified folder item.
WorkspaceFolderName	Read-only	Contains the name of the specified workspace folder.
WorkspaceFoldersCount	Read-only	Contains the number of folders in the specified workspace.
WorkspaceId	Read-only	Contains the identifier of the specified workspace.
WorkspaceName	Read-only	Contains the name of the specified workspace.
WorkspacesCount	Read-only	Contains the number of workspaces.

Examples

The following code example, from the RemoteApp and Desktop Connections workspace API sample, demonstrates how to instantiate and initialize the WorkspaceBrokerAx object.

createInstance: function () {
    var wkspObj = document.createElement("object");
    var wkspRegion = document.getElementById("wkspAxControlRegion");
    wkspRegion.appendChild(wkspObj);

    // Register for standard ActiveX events
    wkspObj.addEventListener("readystatechange", function (e) {
        if (wkspObj.readyState !== 4) {
            WinJS.log && WinJS.log("Error: the ActiveX control readyStateChange fired, but readyState != 4. ReadyState: " + wkspObj.readyState, "sample", "error");
        }
    }, false);
    wkspObj.addEventListener("error", function (e) {
        WinJS.log && WinJS.log("Error loading the ActiveX control", "sample", "error");
    }, false);

    // Hook up the ActiveX control
    wkspObj.id = "wkspAxControl";
    wkspObj.classid = "CLSID:CD70A734-B6DB-4588-9813-FF2E37A4661F";

    return wkspObj;
},

The following code example, from the RemoteApp and Desktop Connections workspace API sample, demonstrates how to enumerate the workspaces and workspace items.

function refreshWorkspaceItems() {
    // Initialize the ActiveX control
    var wkspActiveX = null;
    var hasEverBeenSubscribed = true;

    try {
        wkspActiveX = Microsoft.Sample.WorkspaceBrokerApi.WorkspaceActiveX.createInstance();
    } catch (e) {
        WinJS.log && WinJS.log("Error setting up the Workspace ActiveX control. Error: " + e.number + " " + e.description, "sample", "error");
        return;
    }

    try {
        wkspActiveX.InitializeWorkspaceConfiguration();
    } catch (e) {
        if (e.number === -2147024894) {
            // This is equivalent to 0x80070002 (ERROR_FILE_NOT_FOUND), and is expected if you have never been subscribed to any workspaces on this machine
            hasEverBeenSubscribed = false;
        } else {
            WinJS.log && WinJS.log("Error calling InitializeWorkspaceConfiguration: " + e.number + " " + e.description, "sample", "error");
            wkspActiveX = null;
            return;
        }
    }

    if (!wkspActiveX) {
        WinJS.log && WinJS.log("Cannot continue, Workspace ActiveX control not ready", "sample", "error");
        return;
    }
    if (!hasEverBeenSubscribed) {
        WinJS.log && WinJS.log("No resources to display, you have never been subscribed to a workspace on this machine.", "sample", "status");
        return;
    }

    WinJS.log && WinJS.log("Workspace ActiveX control ready", "sample", "status");

    // First clear out any old resources in the UI
    var itemsRegion = document.getElementById("wkspItems");
    while (itemsRegion.hasChildNodes()) { 
        itemsRegion.removeChild(itemsRegion.lastChild); 
    }

    try {
        var numWorkspaces = wkspActiveX.WorkspacesCount;

        if (numWorkspaces === 0) {
            WinJS.log && WinJS.log("No resources to display, you are currently not subscribed to any workspaces.", "sample", "status");
            return;
        }

        for (var wkspIdx = 0; wkspIdx < numWorkspaces; wkspIdx++) {
            var wkspId = wkspActiveX.WorkspaceId(wkspIdx);
            var wkspName = wkspActiveX.WorkspaceName(wkspIdx);

            var wkspNameTag = document.createElement("h2");
            wkspNameTag.textContent = wkspName;
            itemsRegion.appendChild(wkspNameTag);

            var numFolders = wkspActiveX.WorkspaceFoldersCount(wkspId);
            
            for (var folderIdx = 0; folderIdx < numFolders; folderIdx++) {
                var folderName = wkspActiveX.WorkspaceFolderName(wkspId, folderIdx);

                var folderNameTag = document.createElement("h3");
                folderNameTag.textContent = folderName;
                itemsRegion.appendChild(folderNameTag);

                var numItems = wkspActiveX.WorkspaceFolderContentsCount(wkspId, folderName);
                
                if (numItems > 0) {
                    var listTag = document.createElement("ul");

                    for (var itemIdx = 0; itemIdx < numItems; itemIdx++) {
                        var listItemTag = generateWorkspaceItemElement(wkspActiveX, wkspId, folderName, itemIdx);                          
                        listTag.appendChild(listItemTag);
                    }

                    itemsRegion.appendChild(listTag);
                }
            }
        }
    } catch (e) {
        WinJS.log && WinJS.log("Error displaying workspace resources: " + e.number + " " + e.message, "sample", "error");
        return;
    }

    WinJS.log && WinJS.log("Workspace Resource refresh complete", "sample", "status");
}

function generateWorkspaceItemElement(wkspActiveX, wkspId, folderName, itemIdx) {
    var itemName = wkspActiveX.WorkspaceFolderItemName(wkspId, folderName, itemIdx);
    var itemIcon = wkspActiveX.WorkspaceFolderImageData(wkspId, folderName, itemIdx);
    var itemFileType = wkspActiveX.WorkspaceFolderItemFileExtension(wkspId, folderName, itemIdx);
    var isDesktop = wkspActiveX.IsWorkspaceFolderItemRemoteDesktop(wkspId, folderName, itemIdx);

    // If desired, you can use itemIcon to display an icon image for the resources by generating an HTML tag similar to the following:
    // <img src="data:image/png;base64,contents-of-itemIcon-variable" />

    // If desired, you can distinguish between resources types (e.g. ".rdp" vs. 3rd party file types) by examining the itemFileType variable

    // If desired, you can seperate Desktop from Non-Desktop (e.g. RemoteApp) resources by filtering on the isDesktop variable

    var resourceLinkTag = document.createElement("a");
    resourceLinkTag.textContent = itemName;
    resourceLinkTag.addEventListener("click", function () {
        try {
            wkspActiveX.LaunchWorkspaceItem(wkspId, folderName, itemName, "sample activation context");
        } catch (e) {
            WinJS.log && WinJS.log("Error launching workspace item: " + e.number + " " + e.message, "sample", "error");
        }
    }, false);

    var listItemTag = document.createElement("li");
    listItemTag.appendChild(resourceLinkTag);

    return listItemTag;   
}

Requirements

Minimum supported client	Windows 8 [Windows Store apps only]
Minimum supported server	Windows Server 2012 [Windows Store apps only]
End of client support	Windows 8.1
End of server support	Windows Server 2012 R2
IDL	Wkspbkax.idl
IID	CLSID is defined as CD70A734-B6DB-4588-9813-FF2E37A4661F