Manage XGameSave storage on console (xbstorage.exe) - XBOX Game Development Documentation

Use this tool to manage XGameSave storage on the console. The tool provides the following subcommands and functions.

If you need to manage XGameSave data on PC, you must use the xgamesaveutil.exe command-line tool.

Command	Description
reset	Deletes all local data for the specified PFN and SCID on the console
import	Imports data from the specified XML file to an XGameSave storage space
export	Exports data from an XGameSave storage space to the specified XML file
delete	Deletes data from an XGameSave storage space
generate	Generates dummy data and saves it to the specified XML file
simulate	Simulates out-of-storage-space conditions

xbstorage reset

Erases all local data in XGameSave storage on the local console, restoring it to factory settings. Data persisted to the cloud isn’t modified and is downloaded again, if necessary.

Column 1
xbstorage reset [/force]

Option	Description
/force	Confirms that `XGameSave` storage should be reset. If you run reset without /force, the command doesn’t reset storage.

xbstorage import

Imports the data that’s specified in filename to a XGameSave storage space. This XML file contains the data. For an example, see xbstorage generate in this topic. For more information about the file’s XML format, see Import and export file format in this topic. There are two ways to specify an XGameSave storage space.

If the input file has a ContextDescription section that’s populated correctly, that information is used to specify the XGameSave storage space.
You can also partially or fully specify the storage space by using command-line parameters. These parameters take precedence over the corresponding elements in the input file.

Use the following examples.

  xbstorage import mydata.xml
  xbstorage import mydata.xml /replace
  xbstorage import mydata.xml /machine /scid:2AAEB34B-DAB2-4879-B625-D970069C1D22
  xbstorage import mydata.xml /msa:user@example.com /scid:2AAEB34B-DAB2-4879-B625-D970069C1D22
  xbstorage import mydata.xml /verbose  

Before import, the system attempts to synchronize the specified XGameSave storage space with the cloud by using the same logic that runs when a running app acquires an XGameSave storage space. After the import completes, the console begins uploading the imported data to the cloud in the background. The upload finishes before the cloud lock is released. The behavior differs from the PC tool (xgamesaveutil), which writes data to local storage only and does not trigger an upload to the cloud. For more information, see Manage XGameSave data on PC (xgamesaveutil.exe). If an app with the same primary service configuration identifier (SCID) is running, this operation could cause a race condition and put the contents of the XGameSave storage space in an indeterminate state. If /replace isn’t specified, the containers that are specified in the input file are erased before the blobs that are specified in the input file are written. Containers in the XGameSave storage space that aren’t specified in the input file won’t be touched.

Column 1
xbstorage import file-name [/scid:SCID] [/machine] [/msa:account] [/replace] [/verbose]

Option	Description
file-name	The XML file that contains the data to be imported.
/scid:SCID	The SCID.
/machine	A per-machine XGameSave storage space. This option can’t be used simultaneously with the /msa option.
/msa:account	The account to be used for a per-user XGameSave storage. The user must be signed in to the console for the space to be used. This option can’t be used simultaneously with the /machine option.
/replace	Before import, deletes all containers in the specified `XGameSave` storage space.
/verbose	Displays the status of the import operation.

xbstorage export

Exports data from an XGameSave storage space to the file specified by outfile. The XML file contains the exported data. For an example, see xbstorage generate in this article. For more information about the XML format, see Import and export file format. There are two ways to specify the XGameSave storage space.

If the /context parameter is used and the file name that’s specified by <infile> has a ContextDescription section that’s populated correctly, that file is used to specify the XGameSave storage space.
You can also partially or fully specify the storage space by using command-line parameters. These parameters take precedence over the corresponding elements specified by /context.

Use the following examples.

  xbstorage export exporteddata.xml /context:space.xml
  xbstorage export exporteddata.xml /machine /scid:2AAEB34B-DAB2-4879-B625-D970069C1D22
  xbstorage export exporteddata.xml /msa:user@example.com /scid:2AAEB34B-DAB2-4879-B625-D970069C1D22
  xbstorage export exporteddata.xml /context:space.xml /verbose  

Before export, the system attempts to synchronize the specified XGameSave storage space with the cloud by using the same logic that runs when a running app acquires an XGameSave storage space. If an app with the same primary SCID is running, this operation could cause a race condition and put the contents of the XGameSave storage space in an indeterminate state.

Column 1
xbstorage export outfile [/context:input-file] [/scid:SCID] [/machine] [/msa:account] [/verbose]

Option	Description
outfile	The XML file to which the data is exported.
/context:input-file	The input file from which the space information is to be read.
/scid:SCID	The SCID.
/machine	A per-machine XGameSave storage space. This option can’t be used simultaneously with the /msa option.
/msa:account	An account to be used for a per-user XGameSave storage. The user must be signed in to the console for the space to be used. This option can’t be used simultaneously with the /machine option.
/verbose	Displays the status of the export operation.

xbstorage delete

Deletes all data from an XGameSave storage space. There are two ways to specify the XGameSave storage space.

If you use the /context parameter and the file specified by <input-file> has a ContextDescription section that’s populated correctly, that file is used to specify the XGameSave storage space.
You can also partially or fully specify the storage space by using command-line parameters. These parameters take precedence over the corresponding elements specified by /context.

Use the following examples.

  xbstorage delete /context:space.xml
  xbstorage delete /machine /scid:2AAEB34B-DAB2-4879-B625-D970069C1D22
  xbstorage delete /msa:user@example.com /scid:2AAEB34B-DAB2-4879-B625-D970069C1D22
  xbstorage delete /context:space.xml /verbose  

Before delete, the system attempts to synchronize the specified XGameSave storage space with the cloud by using the same logic that runs when a running app acquires an XGameSave storage space. If an app with the same primary SCID is running, this operation could cause a race condition and put the contents of the XGameSave storage space in an indeterminate state.

Column 1
xbstorage delete [/context:input-file] [/scid:SCID] [/machine] [/msa:account] [/verbose]

Option	Description
/context:input-file	The input file from which the space information is to be read.
/scid:SCID	The SCID.
/machine	A per-machine XGameSave storage space. This option can’t be used simultaneously with the /msa option.
/msa:account	The account to be used for a per-user XGameSave storage. The user must be signed in to the console for the space to be used. This option can’t be used simultaneously with the /machine option.
/verbose	Displays the status of the delete operation.

xbstorage generate

Generates dummy data and saves it to the file specified by <file-name>. For more information about the XML format, see Import and export file format. The SCID is set to 00000000-0000-0000-0000-000000000000, and the account is set for a per-machine XGameSave storage space. To change those values, edit the file directly after generation. Use the following examples.

  xbstorage generate dummydata.xml
  xbstorage generate dummydata.xml /containers:4
  xbstorage generate dummydata.xml /blobs:10
  xbstorage generate dummydata.xml /containers:4 /blobs:10
  xbstorage generate dummydata.xml /containers:4 /blobs:10 /blobsize:512  

The byte data is a simple ascending sequence. For example, a 5-byte blob would have the following bytes: 00 01 02 03 04. To specify a per-user XGameSave storage space, change the Account node in the XML file as shown in the following example.

  
   <Account msa="user@example.com"/>

Column 1
xbstorage generate file-name [/containers:n] [/blobs:n] [/blobsize:n]

Option	Description
file-name	The XML file to which the data is written.
/containers:n	The number of containers to be generated. The default value of n is 2.
/blobs:n	The number of blobs to be generated. The default value of n is 3.
/blobsize:n	The number of bytes per blob. The default value of n is 1024.

xbstorage simulate

Simulates out-of-local-storage conditions for the XGameSave storage service.

Column 1
xbstorage simulate [/reserveremainingspace] [/forceoutoflocalstorage] [/stop] [/verbose]

Option	Description
/reserveremainingspace	Reserves all remaining space in XGameSave storage. Deleting something from XGameSave storage makes some space available for use.
/forceoutoflocalstorage	Simulates the XGameSave storage service that has no available space left. Deleting something from XGameSave storage doesn’t change the XGameSave storage service from reporting out of memory.
/stop	Stops all simulations.
/verbose	Displays the status of the simulate operation.

Common options

Column 1
xbstorage [/?] [/X:address [+accesskey] ]

Option	Description
/?	Displays help for xbstorage.exe.
/X:address [+accesskey]	Use this option to specify the host name or address (shown as Tools IP on the console) of a targeted console without changing the default console. For details about setting a host name for a console, see Setting a host name for the console IP address.If you don’t use this option, the default console (previously set by Connect (xbconnect.exe)) is used.Use the accesskey string to provide console access only to those people who have the access key. Set the access key by using the command xbconfig accesskey=your-key, and then restart your console to make the access key effective.To access a console that’s configured with an access key, include a plus sign (+) and the access key after the IP address or host name of the console.If an access key is provided when the default console is set by xbconnect, the access key is stored as part of the default console’s address.For more information about access keys, see xbconfig accesskey.

Import and export file format

The XML file used with the import, export, and generate commands has the format shown in the following example.

  <?xml version="1.0" encoding="UTF-8"?> 
  <XbConnectedStorageSpace> 
    <ContextDescription> 
      <Account machine="true" /> 
      <Title scid="00000000-0000-0000-0000-000000000000" /> 
    </ContextDescription> 
    <Data> 
      <Containers> 
        <Container name="Container1"> 
          <Blobs> 
            <Blob name="Blob1"> 
              <![CDATA[... ] ]> 
            </Blob> 
            ... 
            <Blob name="BlobN"> 
              <![CDATA[... ] ]> 
            </Blob> 
          </Blobs>
        </Container> 
        ... 
        <Container name="ContainerN"> 
        ... 
        </Container> 
      </Containers> 
    </Data> 
  </XbConnectedStorageSpace>  

The format of data in this XML file isn’t identical to the format on the platform. The format might change in the future, so the files should be treated as if they have an intermediate or utility format, not an archival format. The ContextDescription node is optional. If you’re creating an XGameSave storage space for a user, you can use <Account msa="user@example.com"/> instead of <Account machine="true"/>. Otherwise, you can specify the context on the command line for import. Blobs and containers should have the corresponding names given to them by the game or app for which the file is being generated. The contents of each blob should be a string wrapped in a CDATA tag, which is generated by calling CryptBinaryToStringW with the flag CRYPT_STRING_BASE64, providing the data for that blob as a raw-byte array. Conversely, blob data can be converted back by calling CryptStringToBinary to provide the formerly encrypted string. For an example of using these two functions, see CryptBinaryToString returns invalid bytes.

​xbstorage reset

​xbstorage import

​xbstorage export

​xbstorage delete

​xbstorage generate

​xbstorage simulate

​Common options

​Import and export file format

​See also

xbstorage reset

xbstorage import

xbstorage export

xbstorage delete

xbstorage generate

xbstorage simulate

Common options

Import and export file format

See also