Pull Deployment

Note Pull Deployment is deprecated and will be removed from a future XDK. We recommend using Run from PC Deployment. See xbapp registernetworkshare and Run from PC Deployment in the documentation for more details. If you have issues migrating to Run from PC Deployment please contact Microsoft for assistance.

The push deployment techniques require copying the entire game to the dev kit before running the game, as well as copying changes to those game resources. In contrast, pull technology enables you to leave all game binaries and content on the dev PC for rapid deployment and editing cycles. With pull deployment, you’ll be able to:

• Set up Visual Studio once, making deployment transparent and virtually effortless
• Get your game up and running on the dev kit quickly
• Quickly see changes made to a subset of binaries and content
• Easily bring together compiled game binaries and content from a variety of places on your dev PC and network shares
• Control when a game “sees” changed binaries and content, independent of the file system
• Enable solutions that allow changes made to binaries and content to be seen almost instantly—often without stopping the game
• Ensure that no intellectual property is ever physically located on the dev kit.

When compared with push deployment, pull provides extremely fast deployment times, both in initial deployment and in updating the game with binary or content changes.

• Network Hardware and Usage Considerations
• Command-line Usage
• Visual Studio Usage
• Mapping File
• Game OS (era.xvd) Requirement

Network Hardware and Usage Considerations

When using pull deployment, it is important to note that file reads can be negatively affected by the quality of the network hardware (such as routers, switches, NIC, and cabling), and also by network latency, traffic, and hops. For best results, you should use pull deployment with your dev PC and dev kit on the same gigabit Ethernet switch, preferably using Category 6 cables. You should also avoid performing large-scale network copies (such as using a multithreaded robocopy.exe) and heavy compiles on the dev PC during game testing.

Command-line Usage

Pull deployment can be used without having Visual Studio installed by taking advantage of the command-line tools that are contained in the XDK. This is of particular benefit to non-developer personnel, such as artists and designers. It is also the best way to learn how the pull deployment environment works before implementing more-advanced scenarios.

xbdeploy.exe

Deploy (xbdeploy.exe) is the primary command-line tool for setting up and managing the tasks associated with pull deployment through control of the xbrdevicesrv.exe long-running binary.

xbrdevicesrv.exe

This filename stands for Xbox Remote Device Server. Used for both pull deployment and streaming install simulation, xbrdevicesrv.exe is a behind-the-scenes long-running binary that fulfills block-level file requests coming from the dev kit. All functionality of xbrdevicesrc.exe is accessed through xbdeploy.exe.

Xbrdevicesrv.exe creates an XVD representing the game layout in the location defined by the GetTempPath function, by default, or a location specified by the /temp switch when calling xbdeploy.exe. This XVD is a sparse file and currently has a size limit of 200 GB.

Note Some antivirus software treats folders such as %temp% aggressively and could introduce slowness in file reads, so we recommend using the xbdeploy.exe pull /temp switch.

Xbrdevicesrv.exe can serve multiple games and/or packages to one or more dev kits simultaneously. Its ability to do so effectively is highly dependent on many factors, including network traffic, dev PC hard drive IO bottlenecks, and game binary and/or content file read behavior. It has been optimized for environments where one dev PC is connected to one dev kit on the same gigabit Ethernet switch. Performance is expected to taper off in scaled environments, especially those where more than three dev kits are connected to the same dev PC.

This component determines whether the request maps to the XVD file system or should be redirected to a game file. The verbose output from xbrdevicesrv.exe during pull set-up and subsequent launching of the Visual Studio Direct3D game template can provide insight into how this mapping works.

In normal use, the xbrdevicesrv.exe binary is never run on its own. Instead, all pull-deployment commands are issued through xbdeploy.exe. The only time that xbrdevicesrv.exe is run by itself is when verbose logging is desired.

For more information on enabling verbose logging, refer to File Server (xbrdevicesrv.exe).

Note Verbose mode and logging incurs an approximate 10% degradation in performance and should only be used during diagnostics.

Typical command-line session

The following list describes the steps involved in a typical xbrdevicesrv.exe command-line session.

1. Launch an XDK command prompt with Administrator privileges.
2. Type xbrdevicesrv.exe and press the Enter key.
3. Launch a second XDK command prompt with Administrator privileges.
4. Type xbdeploy.exe pull <apppath> /mf:<filepath> and press the Enter key. <apppath> in the context of the Xbox One Direct3D Game template looks like C:\Users\charlieo\Documents\Visual Studio\Projects\Direct3DGame1\XboxOne\Layout\Image\Loose
   <filepath> is the path to an XML file using the mapping file schema. Note that the /mf switch is optional.
   This is the end of one-time set-up tasks and the start of iterative development.
   
5. Change as much or as little in the game as you like.
6. Type xbdeploy.exe audition <packagefullname> and press the Enter key. The pull system will incorporate file changes into the package.
7. Refresh (or close and relaunch) the game to see the change. The game must reload assets or be restarted regardless of whether the content is updated using push file copy or pull auditioning.
8. Repeat steps 3–5.

Visual Studio Usage

The following steps are required to use pull deployment with Visual Studio.

1. In Visual Studio, open the Xbox One project.
2. On the Project menu, click Properties.
3. Expand Configuration Properties, expand Xbox One, and then click Deploy.
4. Set Deploy Mode to Pull (Run from DevPC).
5. Optionally, set Pull Mapping File to a URI that points to the mapping file.
   If there are no errors, the title will launch on the console.
   

Note

If you initialize a pull session for a title from the loose folder of a VS project using command-line tools or Xbox One Manager, and then rebuild the title in Visual Studio, Visual Studio updates the folder and potentially corrupts the pull session. To recover from this corruption, or to use pull deployment again, the console must be rebooted.

The workaround is to do either of the following:

• Use pull-deployment from the Visual Studio integration, allowing it to monitor and audition changes appropriately.
• Avoid targeting the loose folder using command-line or Xbox One Manager pull-deployment options.

Mapping File

The mapping file allows for multiple locations (sometimes called split asset deployment) to be used for things like game binaries, manifests, and content at a very granular level and in such a way that game code is unchanged from the retail environment.

For example, the compiled sources for a game could look something like this:

For the SMB server file-share example (\\buildserver\sharedfolder), pay attention to the earlier notes about network considerations: although it is supported, this approach could result in poor game performance as a result of network conditions.

To leave those items in their physical locations on the dev PC and bring them together for the dev kit to run, you would author a mapping file as follows:

Contents of D:\MyMappingFile.xml
---------------------------------------------------
<?xml version="1.0" encoding="utf-8" ?>
<mappings>
  <!-- The root package path is created with -->
  <!-- the path passed into to the           -->
  <!-- xbdeploy.exe pull command.           -->
  <path source="D:\enlistment\myfontsfolder"
        target="\fonts" />
  <path source="\\buildserver\sharedfolder"
        target="\textures" />
</mappings>  

And pass this file into the command line in this way:

xbdeploy.exe pull "C:\Users\charlieo\Documents\Visual Studio\Projects\Direct3DGame1\XboxOne\Layout\Image\Loose" /mf:"D:\MyMappingFile.xml"  

The dev kit sees it this way:

C:\Program Files (x86)\Microsoft Xbox One XDK\bin>xbdir.exe {d673df1f-6640-41bb-a09c-3347f4aee155_1.0.0.0_x64__zjr0dfhgjwvde}:\

Directory of {d673df1f-6640-41bb-a09c-3347f4aee155_1.0.0.0_x64__zjr0dfhgjwvde}:\

04/20/2013  02:04 PM  D               fonts
04/20/2013  02:04 PM  D               textures
04/20/2013  02:04 PM      A  262,144  appdata.bin
04/20/2013  02:04 PM      A    1,240  AppxManifest.xml
04/20/2013  02:04 PM      A  466,432  Direct3DGame1.exe
04/20/2013  02:04 PM      A    5,789  Logo.png
04/20/2013  02:04 PM      A      745  SmallLogo.png
04/20/2013  02:04 PM      A    7,126  SplashScreen.png
04/20/2013  02:04 PM      A    1,926  StoreLogo.png

                745,402 bytes
                7 file(s)
                2 dir(s)

C:\Program Files (x86)\Microsoft Xbox One XDK\bin>xbdir.exe {d673df1f-6640-41bb-a09c-3347f4aee155_1.0.0.0_x64__zjr0dfhgjwvde}:\fonts

Directory of {d673df1f-6640-41bb-a09c-3347f4aee155_1.0.0.0_x64__zjr0dfhgjwvde}:\fonts

04/20/2013  02:04 PM      A  38,920  Arial.spritefont

                38,920 bytes
                1 file(s)
                0 dir(s)

C:\Program Files (x86)\Microsoft Xbox One XDK\bin>xbdir.exe {d673df1f-6640-41bb-a09c-3347f4aee155_1.0.0.0_x64__zjr0dfhgjwvde}:\textures

Directory of {d673df1f-6640-41bb-a09c-3347f4aee155_1.0.0.0_x64__zjr0dfhgjwvde}:\textures

04/20/2013  02:04 PM      A  204,896  Background.dds

                204,896 bytes
                1 file(s)
                0 dir(s)  

Very granular and complex development patterns, including deeply nested folders, can be enabled with the mapping file by adding <path> entries. For simple scenarios in which all game binaries and assets are in the Xbox One deployment folder, a mapping file is not needed.

Mapping File Examples

Merge the contents of the two sources to the root location, alongside the loose folders specified with xbdeploy.exe pull <apppath>. It is up to the user specifying the mapping file to manage any merge conflicts.

<?xml version="1.0" encoding="utf-8" ?>
<mappings>
  <path source="C:\folder1"
        target="\" />
  <path source="C:\folder2"
        target="\" />
</mappings>  

Make a single source available in two separate package-relative paths.

<?xml version="1.0" encoding="utf-8" ?>
<mappings>
  <path source="C:\folder"
        target="\path1" />
  <path source="C:\folder"
        target="\path2" />
</mappings>  

Make three sources available in three package-relative paths.

<?xml version="1.0" encoding="utf-8" ?>
<mappings>
  <path source="C:\folder"
        target="\fonts" />
  <path source="D:\folder"
        target="\textures" />
  <path source="E:\folder"
        target="\data" />
</mappings>  

Include all the exe, dll, pak and jpg files under \someserver\mybiggame\2014 and keep the original structure.

<?xml version="1.0" encoding="utf-8" ?>
<mappings>
  <path source=”\\someserver\MyBigGame\2014” target=”\” include=”*.exe|*.dll|*.pak|*.jpg” />
</mappings>  

Include all files under \someserver\mybiggame\2014 except pdb and sym files and keep the original structure.

<?xml version="1.0" encoding="utf-8" ?>
<mappings>
  <path source=”\\someserver\MyBigGame\2014” target=”\” exclude=”*.pdb|*.sym” />
</mappings>  

Include only certain file types from specific directories and explicitly exclude some subdirectories.

<?xml version="1.0" encoding="utf-8" ?>
<mappings>
  <excludepath source=\\someserver\MyBigGame\2014\Engine\PS4_Version” />
  <path source=”\\someserver\MyBigGame\2014\Engine” target=”\” include=”*.exe|*.dll” />
  <excludepath source=\\someserver\MyBigGame\2014\Assets\Raw” />
  <path source=”\\someserver\MyBigGame\2014\Levels\XO” target=”\levels” />
  <path source=”\\someserver\MyBigGame\2014\Assets” target=”\Assets” include=”*.jpg|*.mp3|*.wav|*.mod” exclude=”dev_art.*”/>
  <excludepath source=\\someserver\MyBigGame\2014\Assets\PS4” />
  <excludepath source=\\someserver\MyBigGame\2014\Engine\XO_Version\Exes\Release” />
</mappings>  

Mapping File Schema

The mapping file consists of a mappings node with one or more path and excludepath nodes as children:

<mappings>
  <path source="source path" target="target path on console" include="file pattern to include" exclude="file pattern to exclude">
  <excludepath source="path to exclude"/>
</mappings>  

mappings
  Top level node of the mapping file.

path
  Specifies the path to the source files and the path where the files will appear on the console. Mapping files can have an unlimited number of <path> elements. The path element has the following attributes:

excludepath
  This element defines absolute paths that will be fully excluded from the file set. This includes the specified excluded path and any children.

Note The mapping file is wholly optional. If none is specified with the /mf switch, only the root folder passed into the xbdeploy.exe pull <apppath> will be included in the created XVD.

The Pull Deployment mapping file allows you to use environment variables as part of the source path specification. The environment variable can be the entire source path or a portion of it, just as you would normally see with environment variables in other similar contexts. For example:

<mappings>
  <path source="%HOMEDRIVE%\Users\contoso\Documents\Visual Studio\Projects\Direct3DGame1\Direct3DGame1\Durango\Layout\Image\extra" target="\remoteextra" />
  <path source="%HOMEDRIVE%\Users\contoso\Documents\Visual Studio\Projects\Direct3DGame1\Direct3DGame1\Durango\Layout\Image\moreextra" target="\remotemoreextra" />
  <path source="%HOMEDRIVE%\Users\contoso\Documents\Visual Studio\Projects\Direct3DGame1\Direct3DGame1\Durango\Layout\Image\filterme" target="\remotemoreextra"/>
</mappings>  

Game OS (era.xvd) Requirement

In both push and pull deployment, the era.xvd file is required to be at the root of the package.

See also

Xbox One Deployment

Xbox One Deployment White Paper

Deploy (xbdeploy.exe)