Xbox Live Compute PowerShell Commandlets Documentation

Change Notes

November 2016

Initial release.

Installation instructions:

• Download the Xbox Live SDK or Xbox Live Tools package from the Xbox Game Developer (XGD) site.
• After extracting the contents, navigate to the \Tools\XboxLiveCompute (Just \XboxLiveCompute in the tools package) folder to find the PowerShell .dlls.
• In a PowerShell window opened in the same path as the commandlets, import the Commands.dll using: Import-Module .\Microsoft.Xbox.XboxLiveCompute.Commands.dll. The commands are now ready to use.
• The very first sign-in must be by a user holding “Global Administrator” status in the Azure Active Directory (AAD) tenant. This will prompt an AAD login and consent pop-up. After consent is granted between the Xbox Live Compute PowerShell commands and the AAD tenant, all future sign-ins with Add-XblcAccount will not trigger the pop-up UI.

Setup Commands

Add-XblcAccount

Authenticates with Dev Center by signing in with an AAD account. No other commands will work unless a user has successfully signed in with this command. Note: The very first sign-in must be by a user holding “Global Administrator” status in the AAD tenant. This will prompt an AAD login and consent pop-up window. After consent is granted between the Xbox Live Compute PowerShell commands and the AAD tenant, all future sign-ins with Add-XblcAccount will not trigger the pop-up UI.

Add-XblcAccount
 -Credentials

Remove-XblcAccount

Signs a user out of the active PowerShell session.

Remove-XblcAccount

Select-XblcTitleId

Stores the cloud title ID to be used for the PowerShell session. Subsequent commands will implicitly use this title ID. The command has to be called each time a PowerShell session is started.

Select-XblcTitleId
 -TitleId

Deployment Commands

New-XblcDeployment

New-XblcDeployment initializes the metadata of a cloud game deployment and returns the deployment’s unique ID. Once created, a code package needs to be uploaded and the deployment needs to be “Started” for it to enter the “Running” state. Only DeploymentName, and Sandbox are required to call New-XblcDeployment successfully. The optional parameters can be added later before deploying using Set-XblcDeployment. The default maximum number of deployments is 100.

New-XblcDeployment
 -DeploymentName
 -Sandbox
 *optional*
 -VmSize
 -TenantCount
 -Certificates
 -Assets
 -Endpoints
 -ScaleSettings
 -Tags
 -IsIpSecTeredo

Additional Information

Endpoints

For new titles in development, it is recommended to only provide a name and protocol for your game server’s endpoints. “tcp” and “udp” are the only valid protocols. The value of the mapped port can be retrieved by the port’s name via the GSDK rather than hardcoded into the server executable. This is explained in detail in the Multi-Tenancy document.

For multi-tenant games, only one set of tenant ports needs to be defined. Xbox Live Compute will map the set of ports for each tenant.

For games implementing IPsec and Teredo, setting the isIpSecTeredo flag to “true” will automatically configure the secure networking port. Additional ports can still be passed in via -Endpoints in addition to the secure networking port.

There is a 32 character limit on the endpoint names.

Endpoints can be defined in a .json file and loaded into PowerShell for scripting using:

$myEndpoints = Get-Content .\myEndpoints.json | Out-String

Below is an example of defining a single tcp port named “myEndpoint.”

[
  {
    "name": "myEndpoint",
    "protocol": "tcp"
  }
]

To define two ports per tenant, comma-separate the entries:

[
  {
    "name": "myTcpEndpoint",
    "protocol": "tcp"
  },
  {
    "name": "myUdpEndpoint",
    "protocol": "udp"
  }
]

ScaleSettings

Developers can edit scale settings to set server levels in regions that have already been provisioned by the Xbox Live Compute team. Scale settings can be defined in a .json file and loaded into PowerShell scripts using the following:

$myScaleSettings = Get-Content .\myScleSettings.json | Out-String

Below is an example of valid content for myScaleSettings.json:

[
  {
    "location": "CentralUS",
    "standingBySessions": 5,
    "maxSessions": 20
  }
]

To configure two or more regions, simply comma-separate each object:

[
  {
    "location": "CentralUS",
    "standingBySessions": 5,
    "maxSessions": 20
  },
  {
    "location": "WestEurope",
    "standingBySessions": 10,
    "maxSessions": 50
  },
  {
    "location": "JapanWest",
    "standingBySessions": 5,
    "maxSessions": 30
  }
]

Refer to the appendix to see the full set of accepted location strings.

Tags

Tags can be edited when the deployment is in the “Stopped” state. The maximum number of tags is 24. The maximum number of tags on a deployment is 24. Keys have a 3 character minimum and 32 character maximum. Values have a 3 character minimum and 64 character maximum.

$myTags = @{"tagName1" = "tagValue1"; "tagName2" = "tagValue2"; "tagName3" = "tagValue3"}

Set-XblcDeployment

Set-XblcDeployment provides a way to edit the metadata of a deployment while it is in the “Stopped” state. The one exception to this rule is ScaleSettings which can be set while the deployment is “Running.”” When setting properties with Set-XblcDeployment only the parameters being set need to be specified. There is no need to submit unchanged parameters.

Set-XblcDeployment
 -DeploymentId
 *optional*
 -Sandbox
 -VmSize
 -TenantCount
 -Certificates
 -Assets
 -Endpoints
 -ScaleSettings
 -Tags
 -IsIpSecTeredo

Get-XblcDeployment

Retrieves the metadata of a specific cloud game deployment using the DeploymentId.

Get-XblcDeployment
 -DeploymentId

Get-XblcDeployments

Returns a list of all deployments and their metadata belonging to the selected title.

Get-XblcDeployments

Remove-XblcDeployment

Deletes a cloud deployment from the system. This can only executed if the deployment is in the “Stopped” state. Game packages associated with the deployment will also be deleted. Assets and certificates associated with the deployment have to be removed separately.

Remove-XblcDeployment
 -DeploymentId

Add-XblcGamePackage

Uploads and associated a game package to a deployment. This is a required step for all deployments. At a minimum, the game package must contain the game server executable and a manifest.xml file.

Two game packages are allowed per deployment. The first game package to be uploaded is activated by default. Subsequent package uploads have to be activated using the Activate-XblcGamePackage command. The non-activated package will be overwritten during uploads following the second upload.

Add-XblcGamePackage
 -DeploymentId  
 -GamePackage

Additional Information

Here is an example manifest.xml file. Note that additional settings can be added in the <ConfigurationSettings> section and later retireved via the GSDK.

<Executable>myGame.exe</Executable>
<ConfigurationSettings>
    <Setting name="gameversion" value="Version1" />
    <Setting name="foo" value="bar" />
</ConfigurationSettings>

Activate-XblcGamePackage

Coming in a future release

Start-XblcDeployment

Starts a deployment to the regions and levels specified in the deployment’s scale settings. When a deployment is started it will enter the “Starting” state until a single standingby server is created in each deployment region. At that point the deployment completes and enters the “Running” state.

Start-XblcDeployment
 -DeploymentId

Transition-XblcDeployment

Applies any changes in a deployment’s scale settings to a deployment in the “Running (Not transitioned)” state. This call will cause the deployment to enter the “Transitioning” state temporarily. If the change is applied successfully, the deployment will return to the “Running” state. If the transition operation fails then the deployment will enter the “Running (Transition failed)” state. “Running (Transition failed)” behaves the same way as “Running” in that the deployment is still usable and the transition operation can be retried.

Before a deployment can be transitioned to apply new scale settings, the scale settings must already have been saved using the Set-XblcDeployment command. Modifying the scale settings with the Set-XblcDeployment command will cause the deployment to enter the “Running (Not transitioned)” state.

Transition-XblcDeployment
 -DeploymentId

Stop-XblcDeployment

Stops a deployment that is in the “Running” or the “Failed” state. When Stop-XblcDeployment is called, the deployment will temporarily enter the “Stopping” state while all servers are shut down. When there are no servers remaining, the deployment will enter the “Stopped” state.

Stop-XblcsDeployment
 -DeploymentId

Get-XblcRdpCredentials

Retrieves the username and password pair for a specific deployment. RDP credentials are unique to a deployment and are generated upon the start of a deployment. Consequently, Get-XblcRdpCredentials will return an error when called on a deployment that is stopped.

Get-XblcRdpCredentials
 -DeploymentId

Additional information

RDP information can be used to create a .rdp file. Example contents of “myrdp.rdp:”

full address:s:r181hcwjkwzpoxia3ieirex-2l5icfubk710d2bfip8yelzpuj-1234567890-wus.cloudapp.net
username:s:G3W}QP4BI)O&L9!IF#3C
LoadBalanceInfo:s:Cookie: mstshash=GSDKAgent#GSDKAgent_IN_0

“r181hcwjkwzpoxia3ieirex-2l5icfubk710d2bfip8yelzpuj-1234567890-wus.cloudapp.net” is the domain name of the session host that will be connected to. The session host names can be determined from the respone of Get-XblcSessionHostInfo. “.cloudapp.net” needs to be added after the three-letter region abbreviation. The username must be the deployment-specific username. The final line of the file is a requirement for the RDP file to work with Azure PaaS.

Get-XblcSessionHostInfo

Retrieves a list of session hosts that meet the filter criteria. Session hosts can be filtered by region and state for a given deployment.

Get-XblcSessionHosts
 -DeploymentId
 *optional*
 -Location
 -States  

Asset Commands

These commands are used for creating and managing asset packages. Once uploaded, asset packages can be used by multiple deployments. This can be useful if multiple deployments use the same pieces of static data. The directory where asset packages are extracted to can be found using the GSDK:

utility::string_t AssetRootPath = Microsoft::Xbox::GameServerPlatform::RoleEnvironment::GetLocalResource(U("Assets")).GetRootPath();

New-XblcAsset

Creates an asset object. The asset package needs to be uploaded separately using Add-XblcAssetPackage. The maximum allowed number of assets is 25.

New-XblcAsset
 -AssetName
 *optional*
 -Description

Add-XblcAssetPackage

Uploads the asset package (asset.zip) to the asset object. The maximum asset package size is 100 GB.

Add-XblcAssetPackage
 -AssetId
 -AssetPackage

Get-XblcAsset

Retrieves additional information on the specified asset package.

Get-XblcAsset
 -AssetId

Outputs

Get-XblcAssets

Retrieves a list of asset objects belonging to a title ID.

Get-XblcAssets

Remove-XblcAsset

Removes an asset package from storage so long as there are no deployments referencing the asset package.

Remove-XblcAsset
 -AssetId

Certificate Commands

These commands are for creating and managing certificates.

New-XblcCertificate

Creates and uploads a certificate. Like asset packages, certificates are shared across a title. There is a 50KB limit on the size of the certificate. The maximum allowed number of certificates is 25.

New-XblcCertificate
 -Filepath
 -Password

Get-XblcCertificate

Retrieves additional information on an individual certificate.

Get-XblcCertificate
 -CertificateId

Get-XblcCertificates

Retrieves a list of all certificate objects belonging to a title.

Get-XblcCertificates

Remove-XblcCertificate

Deletes a certificate. A certificate can only be deleted if it is not being used by any deployments.

Remove-XblcCertificate
 -CertificateId  

Journal Commands

These commands are used for configuring a connection to Journal. Journal is Xbox Live Compute’s telemetry pipeline based on Azure Event Hubs.

Register-XblcJournalEventHub

Registers an Event Hub with Journal. Once registered, Journal events will start arriving at the Event Hub automatically. The same Event Hub can be registered for multiple titles.

Register-XblcJournalEventHub
 -EventHubName
 -EventHubConnectionString

Unregister-XblcJournalEventHub

Unregisters an Event Hub from Journal. After an Event Hub is unregistered, it will stop receiving Journal events.

Unregister-XblcJournalEventHub
 -EventHubName

Get-XblcJournalEventHubs

Retrieves a list of all Event Hubs for a title.

Get-XblcJournalEventHubs

Other Commands

Get-XblcCommandletInfo

Returns the version number and release date of the commandlet package.

Get-XblcCommandletInfo

Appendix

Available VM sizes

More information on VM specifications and regional availability can be found here.

Available Azure regions

Regions coming soon: Central India, South India, West India, Canada Central, Canada East, UK South, UK West

Example Scripts

Create and start deployment script

##Load the commandlets
Import-Module .\Microsoft.Xbox.XboxLiveCompute.Commands.dll

##Sign in
$username = "Bill@contosostudios.onmicrosoft.com"
$secpassword = ConvertTo-SecureString "MyPassword" -AsPlainText -Force
$credentials = New-Object System.Management.Automation.PSCredential($username, $secpassword)
Add-XblcAccount -Credentials $credentials

##Select the title id
$titleId = 123456789
Select-XblcTitleId -TitleId $titleId

##Upload assets
$assetId1 = New-XblcAsset -Name "Asset1" -Description "This is the first asset"
Add-XblcAssetPackage -AssetId $assetId1 -AssetPackage ".\asset1.zip"

##Upload certificates
$certId1 = New-XblcCertificate -Filepath ".\cert1.pfx" -Password "password1"
$certId2 = New-XblcCertificate -Filepath ".\cert2.pfx" -Password "password2"

##Initialize deployment properties
$name = "MyDeployment"
$sandbox = "RETAIL"
$tenantCount = 2
$vmSize = "Standard_D1v2"

##Load json content in as a string
$endpoints = Get-Content .\defaultendpoints.json | Out-String
$scaleSettings = Get-Content .\defaultscalesettings.json | Out-String

$tags = @{"tag1" = "value1"}
$assets = $assetId1
$certificates = $certId1,$certId2

##Create deployment
$deploymentId = New-XblcDeployment -Name $name -Sandbox $sandbox -TenantCount $tenantCount -VmSize $vmSize -ScaleSettings $scaleSettings -Endpoints $endpoints -Tags $tags -Assets $assets -Certficiates $certificates

##Upload game package
$gameFilepath = ".\MyGame.zip"
Add-XblcGamePackage -DeploymentId $deploymentId -GamePackage $gameFilepath

##Start deployment
Start-XblcDeployment -DeploymentId $deploymentId

Editing Scale Scale Settings on a Running Deployment

This script shows how to apply new scale settings to an already running deployment.

##Load in new scale settings
$newScaleSettings = Get-Content .\newScalesettings.json | Out-String

##Get the deployment Id of the running deployment you need to edit
$deploymentId = c3c1b91e-235f-42e8-9d8e-7a2d1333489e

##Save the new metadata to the object
Set-XblcDeployment -DeploymentId $deploymentId -ScaleSettings $newScaleSettings

##Apply the new scale settings to the running game
Transition-XblcDeployment -DeploymentId $deploymentId

Adding and Removing Regions with Scale Settings

To add a region to an already running deployment, simply add the appropriate JSON to the scale settings to include the additional region or regions.

Example 1 A game with the following scale settings would only be running in CentralUS.

[
  {
    "location": "CentralUS",
    "standingBySessions": 5,
    "maxSessions": 20
  }
]

Example 2 Setting and transitioning the deployment using the following scale settings would add WestEurope and JapanWest to the deployment without affecting CentralUS.

[
  {
    "location": "CentralUS",
    "standingBySessions": 5,
    "maxSessions": 20
  },
  {
    "location": "WestEurope",
    "standingBySessions": 10,
    "maxSessions": 50
  },
  {
    "location": "JapanWest",
    "standingBySessions": 5,
    "maxSessions": 30
  }
]

Example 3 Setting and transitioning the deployment again using the following scale settings would shut down WestEurope and Japan West while deploying AustraliaEast and leave CentralUS unaffected.

[
  {
    "location": "CentralUS",
    "standingBySessions": 5,
    "maxSessions": 20
  },
  {
    "location": "AustraliaEast",
    "standingBySessions": 10,
    "maxSessions": 50
  }
]