Console Extensions API

The Devkit Console Extensions library (Microsoft.Xbox.Tools.ConsoleExtensions) allows you to write a shared resource app that installs packaged apps (and games), enumerates installed apps, launches installed apps, and performs network tracing and simulation. This library can be used on a Devkit (only on a Devkit) to write a custom app that can be used to install and launch your game when a DevPC is not attached to the console.

Note The Microsoft.Xbox.Tools.ConsoleExtensions namespace is designed to allow you to automate common developer console tasks such as installing your exclusive resource game. The full Microsoft.Xbox.Tools.ConsoleExtensions namespace is available to SRA apps as part of the ADK. A subset of the Microsoft.Xbox.Tools.ConsoleExtensions namespace is available to ERA apps as part of the XDK.

Using the Microsoft.Xbox.Tools.ConsoleExtensions Namespace

To use the ConsoleExtensions library:

  1. Install the version of the ADK that matches the version of the XDK you have installed.
  2. In Visual Studio, create a new project by selecting Javascript -> Xbox One -> Blank App
  3. Add a Reference to the Microsoft.Xbox.Tools.ConsoleExtensions namespace by selecting Xbox.adk->Extensions->Xbox DevKit Extensions in the Reference Manager dialog
  4. Add code that uses the PackageInstallManager, ApplicationManager, TraceManager, or SimulationManager classes. For example, to launch your exclusive resource game you would use ApplicationManager.launch: 
    Microsoft.Xbox.Tools.ConsoleExtensions.ApplicationManager.launch("Achievements110_zjr0dfhgjwvde!AchievementsProfile");

Common Scenarios

The Console Extensions API (Microsoft.Xbox.Tools.ConsoleExtensions) provides the ability to automate common tasks on a devkit when no development PC is attached.

The following are examples of common scenarios the Console Extensions API allows you to automate:

Installing a Package

Application packages can be installed using the PackageInstallManager.InstallAsync method.

var installUrlForOurGame = "http://gameserver/xvcs/StreamingInstall_1.0.0.0_x64__zjr0dfhgjwvde";
installManager.InstallAsync(installUrlForOurGame).done(
    function (result) {
        this._writeLog("Installation of " + result.packageFullName + " Completed!");
    }, 
    function (error) {
        this._writeLog("*** Installation failed. Error Code: " + error);
    },
    function (progress) {
        this._writeLog("Installing " + progress.stage + " for " 
                 + progress.packageFullName + " " + progress.percentComplete + "% complete.");                        
    }
);

Launching an App

Apps can be launched using the ApplicationManager.Launch method.

//Launch the Settings app
_handleLaunchSettingsButtonInvoked: function () {
    try {
        appManager.launch("Achievements110_zjr0dfhgjwvde!AchievementsDebug");
    } catch (e) {
        this._writeError("Failed to launch app", e);
    }
},

Setting the Default App for a Package

The default app for a package can be set using the ApplicationManager.SetDefaultApp method.

//Set the default app to be the Profile build
_handleDefaultDebugButtonInvoked: function () {
    appManager.setDefaultApp("54ce29f9", "Achievements110_zjr0dfhgjwvde!AchievementsProfile");
},

Enumerating Packages and Apps

The list of packages and apps on a console can be retrieved using the ApplicationManager.GetInstalledPackages method.

//Get the list of packages and apps and translate it into a flat list of apps
_getAppList: function () {
    var applications = new Array();
    var installPackages = appManager.getInstalledPackages()
    var index = 0;	
    installPackages.forEach(
        function iteratePackage(installedPackage) {
            installedPackage.applications.forEach(
                function addPFN(applicationInfo) {
                    var newApp = new application(installedPackage, applicationInfo);
                    applications[index] = newApp;
                    index++;
                }
            )
        }
    )
    return applications;
},

Start a Packet-level Network Trace

Network traces can be started using the TraceManager.StartAsync method.

var XtfTraceManager = Microsoft.Xbox.Tools.ConsoleExtensions.TraceManager;        
var traceType = Microsoft.Xbox.Tools.ConsoleExtensions.TraceType.networkPacket;

XtfTraceManager.startAsync(traceType).then(

    function complete() {
        // Handle success here 
        writeLog("TraceManager.startAsync succeeded");
    }.bind(this),

    function error(e) {
        // Handle error here 
        writeError("TraceManager.startAsync error: ", e);
    }.bind(this)
);

Stop a Packet-level Network Trace

Network traces can be stopped using the TraceManager.StopAsync method. After the trace has stopped, the resulting trace file will be available in the xbTrace directory of the SystemScratch drive (typically accessed as d:\xbTrace) on the console. The trace files can be copied back to the PC using either xbcp or SMB.

var XtfTraceManager = Microsoft.Xbox.Tools.ConsoleExtensions.TraceManager;
XtfTraceManager.stopAsync().then(

    function complete(result) {
        // Handle success here 
        var logText = "TraceManager.stopAsync succeeded";

        writeLog("TraceManager.stopAsync succeeded");
        writeLog(result.type.toString());
        writeLog(result.Duration.duration.toString());

        // The filePath property contains the name of the resulting trace file on the 
        // console's d: drive
        writeLog(result.filePath.toString());
        writeLog(result.eventsLost.toString());
        writeLog(result.errorCode.toString ());

    }.bind(this),

    function error(e) {
        // Handle error here 
        writeError("TraceManager.stopAsync error", result.errorCode.toString());
    }.bind(this)
);

Start a Network Simulation

Network simulations can be started using the SimulationManager.StartAsync method.

var XtfSimulationManager = Microsoft.Xbox.Tools.ConsoleExtensions.SimulationManager;        
var networkSim = Microsoft.Xbox.Tools.ConsoleExtensions.SimulationType.network;
var netSimProfile = Microsoft.Xbox.Tools.ConsoleExtensions.SimulationProfile.networkMinimum;

XtfSimulationManager.startAsync(networkSim, netSimProfile).then(

    function complete() {
        // Handle success here
        writeLog("SimulationManager.startAsync succeeded");
    }.bind(this),

    function error(e) {
        // Handle error here 
        writeError("SimulationManager.startAsync error: ", e);
}.bind(this)

);

Stop a Network Simulation

Stop running simulations using SimulationManager.StopAsync.

var XtfSimulationManager = Microsoft.Xbox.Tools.ConsoleExtensions.SimulationManager;        
XtfSimulationManager.stopAsync().then(

    function complete() {
        // Handle success here
        writeLog("SimulationManager.stopAsync succeeded");
    }.bind(this),

    function error(e) {
        // Handle error here 
        writeError("SimulationManager.stopAsync error: ", e);
    }.bind(this)

);

Get Simulation Status

The getStatusAsync method on the SimulationManager class can be used to determine which simulations, if any, are running.

var XtfSimulationManager = Microsoft.Xbox.Tools.ConsoleExtensions.SimulationManager;        
XtfSimulationManager.getStatusAsync().then(

    function complete(result) {
        // Handle success here
        writeLog("SimulationManager.getStatusAsync succeeded");

        if (result.size == 0) {
            writeLog("No simulations are currently running");
        } else {

            result.forEach(
                // Display information for each simulation that is running
                function displaySimStatusRecord(simStatus) {
                    writeLog(simStatus.profile.toString());
                    writeLog(simStatus.type.toString());
                }
            )
        }

    }.bind(this),

    function error(e) {
        // Handle error here 
        writeError("SimulationManager.getStatusAsync error: ", e);
    }.bind(this)

);

Blocking Access to Xbox Live Services

The StartSimulationNetworkChannelsAsync method on the SimulationManager class can be used to start advanced network simulations by allowing you to specify different performance for portions of the network.

var XtfSimulationManager = Microsoft.Xbox.Tools.ConsoleExtensions.SimulationManager;
var networkAddresses = ["134.170.28.0/255.255.254.0",
"191.232.80.128/255.255.255.128",
"191.232.82.128/255.255.255.128",
"191.234.78.0/255.255.254.0",
"131.253.28.0/255.255.254.0",
"134.170.176.0/255.255.252.0",
"157.56.70.0/255.255.254.0",
"65.55.42.0/255.255.254.0",
"131.253.22.0/255.255.254.0",
"191.234.240.0/255.255.248.0"];

var networkChannelProfile = new Microsoft.Xbox.Tools.ConsoleExtensions.SimulationNetworkChannelProfile(
  0,
  Microsoft.Xbox.Tools.ConsoleExtensions.SimulationProfile.networkBroken,
  networkAddresses
);

var networkChannelProfiles = [];

networkChannelProfiles.push(networkChannelProfile);

// add more channel profiles if desired 

XtfSimulationManager.startSimulationNetworkChannelsAsync(networkChannelProfiles).then(
  function complete() {
    // Handle success here
    writeLog("SimulationManager.startSimulationNetworkChannelsAsync succeeded");
  }.bind(this),
  function error(e) {
    // Handle error here 
    writeError("SimulationManager.startSimulationNetworkChannelsAsync error: ", e);
  }.bind(this)
);

See also

Microsoft.Xbox.Tools.ConsoleExtensions Namespace