Deploy builds using PowerShell/API

This article provides an overview on how to deploy/create builds for VMs using Windows OS in PowerShell on a Windows 10 development device. When deploying a build using PowerShell/API, you’re likely to be using a combination of using Game Manager and the APIs. Hence, the PowerShell/API commands are listed by functionality below. If this is your first time deploying a build, we recommend deploying a build using the Wrapper sample because it comes with all the assets you need to actually deploy servers.

In order to use and view the PlayFab Multiplayer Servers, you need to enable the feature. If you are a new user, we recommend that you use the Game Manager method to enable this feature. For instructions, see Enable the PlayFab Server feature.

Get your title ID and developer secret key

Get your PlayFab title ID
- Log into your developer account on PlayFab.com
- In Game Manager, go to My Studios and Titles page. Look for your game title and get the PlayFab game title ID
Get the developer secret key for the title
- In Game Manager, select your title > settings (gear icon)
- Select Title settings, then select the Secret Keys tab to get the developer secret key

For more information about secret keys, see Secret key management.

Install the PlayFab MultiplayerAPI PowerShell module

Open Windows PowerShell as an Administrator
If you have previously installed PlayFab Multiplayer PowerShell module, uninstall it with following command. This module is now deprecated.

Uninstall-Package PlayFabMultiplayer

To help you transition to the new module, see Mapping commands to find the new equivalent commands. Be aware that both the commands and arguments could be different.

Install the new PlayFabMultiplayer API module

For detailed documentation about each command, see Cmdlet documentation.

Install-Module -Name PlayFabMultiplayerApi

Before installing the module, you may need to set your execution policy by running Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser in PowerShell first. To learn more, see PowerShell execution policies.

Learn more about the cmdlets in the PlayFab Multiplayer PowerShell module by running the following command. Or you can refer to the PlayFabMultiplayerApi cmdlet reference documentation.

Get-Command -Module PlayFabMultiplayerApi | Get-Help

Obtain an EntityToken for your title

Run the following command using your title ID and associated developer key. You must run this command at the start of any session when using the PlayFabMultiplayerApi PowerShell module. It calls the GetEntityToken API to obtain an EntityToken and stores it in an environment variable for use in future cmdlets.

Set-PfTitle -TitleID "mytitleID" -SecretKey "mysecretkey"

Enable multiplayer servers feature for your title

Run this cmdlet below to enable the Multiplayer Servers features. It calls the enable multiplayer servers API.

Enable-PfMultiplayerServer

If you receive an error that says Title must have a valid payment instrument associated with it in order to enable Multiplayer Servers, see Enable PlayFab Multiplayer Servers using Game Manager to add your payment information.

Upload an asset

Uploading an asset is mandatory when you’re deploying a build for Windows servers. This is because your assets customize the managed Windows container image. However, it’s optional when deploying a build for Linux servers since you’re able to customize the Linux container image. To learn more, see Create and deploy Linux Builds. Run this command to upload an asset.

New-PfAsset -FilePath C:\MyAsset.zip -AssetName MyAsset.zip

where:

Filepath: Path to the local file you want to upload
AssetName: Name of the asset to upload

For more details, see New-PfAsset reference documentation.

Create a build

When creating a build for Windows servers, you need to have uploaded an asset. If not, see Upload an asset.
When creating a build for Linux servers, you need to have uploaded your custom Linux container image to your PlayFab container registry. To learn more, see Create and deploy Linux Builds.

Make sure you use the correct values for $vmSize__ and __$ regions if you plan to take advantage of resources offered for free evaluation.

Sample code below to help deploy builds for Windows game servers.

$vmSize = "Standard_D2as_v4"
$regions = @( @{ StandbyServers = 1; MaxServers = 1; Region = 'EastUS'; ScheduledStandbySettings = $NULL } )
$ports = @( @{ Name = 'tcp_port'; Num = 8080; Protocol = 'TCP' }, @{ Name = 'udp_port'; Num = 8081; Protocol = 'UDP' } )
$gameAssets = @( @{ FileName = 'MyAsset.zip'; MountPath = 'C:\Assets' } )

$buildResponse = New-PfBuild -BuildName ExampleBuild -ContainerFlavor ManagedWindowsServerCore -StartMultiplayerServerCommand 'C:\Assets\MyCustomServer.exe' -GameAssetReferences $gameAssets -VMSize $vmSize -MultiplayerServerCountPerVM 1 -Ports $ports -RegionConfigurations $regions

# All PlayFabMultiplayerApi cmdlets return objects, so we can pass the returned object to ConvertTo-Json for human readability.
$buildResponse | ConvertTo-Json -depth 5

Sample code below to help deploy builds for Linux game servers.

$vmSize = "Standard_D2as_v4"
$ports = @( @{ Name = 'tcp_port'; Num = 8080; Protocol = 'TCP' }, @{ Name = 'udp_port'; Num = 8081; Protocol = 'UDP' } )
$regions = @( @{ 'MaxServers' = 1; 'Region' = 'AustraliaEast'; StandbyServers = 1; 'ScheduledStandbySettings' = $NULL } )
$containerImageReference = @{ ImageName = "MyLinuxContainerImage"; Tag = "0.2" }

$buildResponse = New-PfBuild -BuildName ExampleBuild -ContainerFlavor CustomLinux -ContainerImageReference $containerImageReference -VMSize $vmSize -MultiplayerServerCountPerVM 1 -Ports $ports -RegionConfigurations $regions

# All PlayFabMultiplayerApi cmdlets return objects, so we can pass the returned object to ConvertTo-Json for human readability.
$buildResponse | ConvertTo-Json -depth 5

During development, shut off any unused or unhealthy regions to avoid VM core hour usage. Core hour usage begins during VM startup and continues until the VM is shut off. VMs in a region will not automatically be shut off unless the region’s target standby servers reach 0, or a region is deleted.

Shutting down VMs

There are three ways to shut down VMs

Set a region’s target standby to 0, this will shut down VMs for this region only.
Delete a specific region from a build.
Delete the whole build, this will shut down VMs across all regions for this build.

List deployed builds

To see a list of builds for your title, run the commands below.

Get-PfBuild | ConvertTo-Json -depth 5

Request a multiplayer server

Once you’ve created a build, one or more servers will be created after running your .exe file. These servers are now “standing by”. You can see them when you list all the servers running our build using this command.

Get-PFMultiplayerServer -BuildId $buildResponse.data.BuildId -Region "EastUS"

Once we see some standby servers, let’s request one for gameplay…

$sessionId = New-Guid
$serverResponse = Request-PfMultiplayerServer -BuildId $buildResponse.data.BuildId -PreferredRegions @('EastUS') -SessionId $sessionId

The response to that call includes an IPv4 address and port number that clients can connect to. For WindowsRunnerCSharp.exe, it hosts a simple webserver so you can browse to the IPv4 address and port number to get a response:

curl "http://$($serverResponse.data.Ipv4Address):$($serverResponse.data.Ports[0].Num)"

This is the core of PlayFab multiplayer servers: within 3 seconds of your matchmaking service calling RequestMultiplayerServer, PlayFab will allocate a new server. These servers come from continuously refilled, standing-by server pools you configure on a per-region and per-build basis.

Mapping commands

Table below shows the new equivalent of the old commands. This is a quick mapping to help those who have used the previous version of the PowerShell module and need to convert their existing commands. Make sure to read the definition of each command to get full details of the change since some of the arguments have also changed.

MultiplayerPowershell command (Old)	MpsPowershell API module (New)
Add-PFMultiplayerAsset	New-PfAsset
Add-PFMultiplayerCertificate	Invoke-PfUploadCertificate
Enable-PFMultiplayerServer	Enable-PfMultiplayerServer
Get-PFMultiplayerAsset	Get-PfAssetSummary
Get-PFMultiplayerBuild	Get-PfBuild
Get-PFMultiplayerCertificate	Get-PfCertificateSummary
Get-PFMultiplayerContainerImages	Get-PfContainerImage
Get-PFMultiplayerImageTags	Get-PfContainerImageTag
Get-PFMultiplayerQosServer	Get-PfQosServer
Get-PFMultiplayerServer	Get-PfMultiplayerServer
Get-PFTitleEntityToken	deprecated
New-PFMultiplayerBuild	New-PfBuild
New-PFMultiplayerServer	Request-PfMultiplayerServer
Remove-PFMultiplayerAsset	Remove-PfAsset
Remove-PFMultiplayerBuild	Remove-PfBuild
Remove-PFMultiplayerCertificate	Remove-PfCertificate
Remove-PFMultiplayerContainerImageTag	Invoke-PfImageUntagContainer
Set-PFTitle	Set-PfTitle

XBOX Services

PlayFab

Get your title ID and developer secret key

Install the PlayFab MultiplayerAPI PowerShell module

Obtain an EntityToken for your title

Enable multiplayer servers feature for your title

Upload an asset

Create a build

Shutting down VMs

List deployed builds

Request a multiplayer server

Mapping commands

See also

​Get your title ID and developer secret key

​Install the PlayFab MultiplayerAPI PowerShell module

​Obtain an EntityToken for your title

​Enable multiplayer servers feature for your title

​Upload an asset

​Create a build

​Shutting down VMs

​List deployed builds

​Request a multiplayer server

​Mapping commands

​See also

Get your title ID and developer secret key

Install the PlayFab MultiplayerAPI PowerShell module

Obtain an EntityToken for your title

Enable multiplayer servers feature for your title

Upload an asset

Create a build

Shutting down VMs

List deployed builds

Request a multiplayer server

Mapping commands

See also