Freigeben über

ClickOnce publishing integration and improved Windows game deployment in XNA Game Studio 3.0

  • Artikel

Important note: The information in this blog post is specific to the XNA Game Studio 3.0 beta. There have been some changes in the final release of XNA Game Studio 3.0. For more information about Windows game publishing using the final release of XNA Game Studio 3.0, please refer to the updated blog post at https://blogs.msdn.com/astebner/archive/2008/10/31/9027445.aspx .  

As previously noted, the XNA Game Studio 3.0 beta has been released.  One of the features that we added in the beta is ClickOnce publishing support for XNA Framework-based Windows games.  I wanted to go over the behind-the-scenes details for this feature and explain how to configure and use it in a Windows game.

What is ClickOnce and why hasn't it worked in the past for games?

ClickOnce is an application deployment technology that can be used to publish applications to Web servers or network file shares for simplified installation scenarios.  ClickOnce features have been available in Visual Studio for a couple of versions, but have not worked well with XNA Game Studio for a couple of reasons:

  1. In XNA Game Studio 2.0, the output of nested content projects was not included in the ClickOnce publishing output when publishing in Visual Studio.  There are some advanced steps that can be used to work around this, but they require in-depth ClickOnce knowledge and also require running publishing tools outside of Visual Studio (such as mage.exe and mageui.exe).
  2. Prerequisites needed to run XNA Framework-based games on computers that do not have XNA Game Studio installed have not been integrated into the Visual Studio publishing process in the past, and the requirements for manually creating installers have been poorly (or worse - inaccurately) documented.

Changes made in the XNA Game Studio 3.0 beta for ClickOnce scenarios

We have addressed the above issues in the XNA Game Studio 3.0 beta by doing the following:

  1. Updating our build steps to properly include nested content project output in the ClickOnce publishing output for a Windows game.
  2. Creating a Visual Studio bootstrapper package for the XNA Framework Redistributable 3.0 that can be included as a prerequisite for ClickOnce-based installers and/or Windows Installer-based installers.
  3. Configuring XNA Game Studio 3.0 Windows game projects to have a dependency on the XNA Framework Redistributable 3.0 bootstrapper package so that this prerequisite will be included by default when publishing Windows games using ClickOnce.
  4. Moving the DirectX runtime files required for XNA Framework-based games into the XNA Framework redistributable so they do not need to be installed as a separate step anymore.

How to publish an XNA Game Studio 3.0 Windows game

There are a couple of ways to access publishing functionality in Visual C# 2008 Express Edition or Visual Studio 2008.  The following steps will allow you to publish using the default settings for prerequisite packages:

  1. Open Visual C# 2008 Express or Visual Studio 2008.
  2. Create a new XNA Game Studio 3.0 Windows game project.
  3. Click on the Build menu and choose Publish <game> - this will launch the Visual Studio Publish Wizard.
  4. Specify the publishing output location.
  5. Choose the installation mechanism to offer to your users - install from the Web, install from a UNC path or file share, or install from a CD/DVD.
  6. Choose whether or not to enable automatic updates for your game.
  7. Click Finish to publish (which will trigger a build automatically if your build output is out of date).

ClickOnce publishing output

The above steps will produce a publishing output folder that contains the following:

  • setup.exe - this is the setup executable for your game, and it contains logic to install prerequisites and then trigger ClickOnce to deploy your game payload
  • <game>.application - this is the ClickOnce deployment manifest for your game
  • Application Files folder that contains your game payload
  • xnafxredist30 folder that contains the XNA Framework Redistributable 3.0 MSI

The above steps will automatically configure your game to include the .NET Framework 3.5 and the XNA Framework Redistributable 3.0 as prerequisites.  It will use the default deployment settings for each of these prerequisites.  For the .NET Framework 3.5, this means that setup.exe will detect whether or not the user's system needs the .NET Framework 3.5 and will download and install it if it is missing.  For the XNA Framework Redistributable 3.0, it will deliver the MSI as payload in a sub-folder next to setup.exe (in the beta only).

In the XNA Game Studio 3.0 beta, you will notice that publishing a Windows game will result in a warning in the error list that states the following:

No 'HomeSite' attribute has been provided for 'Microsoft XNA Framework Redistributable 3.0', so the package will be published to the same location as the bootstrapper.

We did not specify a HomeSite value in the beta because we did not post the XNA Framework Redistributable 3.0 MSI as a separate download.  In the final release of XNA Game Studio 3.0, we will post the XNA Framework Redistributable 3.0 MSI as a separate download, and we will update this bootstrapper package to specify a valid HomeSite value.  That will cause the default publishing behavior to be to cause setup.exe to detect whether or not the user's system needs the XNA Framework Redistributable 3.0 and to download and install it if it is missing (like the default behavior for the .NET Framework 3.5).

How to configure non-default ClickOnce publishing options

In order to change the default publishing behavior for XNA Game Studio 3.0 Windows game, you can use the following steps:

  1. Right-click on your Windows game project in the Visual Studio Solution Explorer and choose Properties.
  2. In the property pages, select the Publish tab.
  3. Use the Application Files... button to exclude payload from your publishing output.
  4. Use the Prerequisites... button to add/remove prerequisite packages or to change how they are packaged (download from the manufacturer's web site, download from the same location as the application, package in a directory along with the game).
  5. Use the Updates... button to enable automatic update checking and configure the update details.
  6. Use the Options... button to configure other advanced ClickOnce options.
  7. Use the Publish Wizard... button to invoke the publishing wizard (the same one that appears if you click on the Build menu and choose Publish <game> in the previous set of steps.
  8. Use the Publish Now button to publish using the default publishing settings without stepping through the wizard.

Notes about installing Windows games using ClickOnce

After publishing your game, you can install it on another system by running setup.exe or by running <game>.application (if the target system already has the .NET Framework 2.0 or higher, it will know how to handle the .application file extension).  Any missing prerequisites will be installed, and then your game will be deployed.  Here are a few key notes about this deployment process:

  • ClickOnce applications are deployed as per-user application to a randomly-generated folder under the currently logged in user's %LOCALAPPDATA% folder.  This folder is chosen automatically by ClickOnce, and you do not have any control over this location in the publishing process.
  • ClickOnce will create a Start menu shortcut for your game.
  • ClickOnce will create an Add/Remove Programs entry so that the user can uninstall the game later.
  • If you choose to include automatic updates for your game, ClickOnce will check for new versions of your game each time the user launches it, and will deploy new versions if they are available.

Using a setup/deployment project to create a game installer

Visual Studio Professional Edition and higher offers the ability to create MSI-based installers in addition to ClickOnce packages.  Both of these deployment solutions use the same bootstrapper packages for installing prerequisites.  This means you can also use a setup/deployment project in Visual Studio 2008 Professional Edition and higher to create an MSI to install your game, and then include the XNA Framework Redistributable 3.0 as a prerequisite.

It is important to note that XNA Game Studio 3.0 does not support automatically adding game or content project output to the setup project (which is normally done by right-clicking the setup project, choosing Add | Project output... and selecting the primary output of the desired project in the Add Project Output Group dialog).  As a result, you will have to manually add the binary files and content files that you want to install as a part of your game to your setup project one-by-one if you choose this option.

Here are steps that you can use to accomplish this:

  1. Open Visual Studio 2008 Professional or higher (setup/deployment projects are not available in the Standard or Express Editions).
  2. Create a new XNA Game Studio 3.0 Windows game project.
  3. Right-click on the solution in the Visual Studio Solution Explorer and choose Add | New Project...
  4. Go to Other Project Types | Setup and Deployment and add a Setup Project.
  5. Use the File System designer to populate the project with the payload of your game (content plus game binaries).  To do this, right-click on your setup project and choose View | File System.  Then create folders and add files in the desired locations.
  6. Right-click on your setup project in the Solution Explorer and choose Properties.
  7. Change the configuration drop down if you want the changes to affect both debug and release builds.
  8. Click on the Prerequisites... button to bring up the Prerequisites selection dialog.
  9. Scroll to the bottom and check the item named Microsoft XNA Framework Redistributable 3.0, then click OK.
  10. Build your solution.

After a build, your setup project's output directory will contain the following:

  • setup.exe - this is the setup executable for your game, and it contains logic to install prerequisites and then trigger the installation of your MSI
  • <game>.msi - this is the Windows Installer MSI file that contains your game payload
  • xnafxredist30 folder that contains the XNA Framework Redistributable 3.0 MSI

In the XNA Game Studio 3.0 beta, you will see the same warning about the HomeSite attribute as described above in the ClickOnce publishing steps.  This is because the same underlying bootstrapper package is used by ClickOnce and setup/deployment projects.  In the final release of XNA Game Studio 3.0, it will be possible to enable download-and-install-on-demand scenarios for the XNA Framework Redistributable 3.0.

Important note about the contents of the XNA Framework Redistributable 3.0

The above information describes how to create an installer for an XNA Framework-based Windows game.  There are a couple of key scenarios that are not currently possible when deploying a Windows game to a system in this way because the necessary functionality is only installed by XNA Game Studio, not by the XNA Framework Redistributable:

  • The Microsoft Games for Windows - LIVE Redistributable package is installed during XNA Game Studio setup, but it is not available for redistribution as a part of a game installer.  A Windows game that attempts to use networking functionality provided by this package on a system without XNA Game Studio installed will encounter a GamerServicesNotAvailableException.
  • The Content Pipeline Build Runtime is installed during XNA Game Studio setup, but it is not included in the XNA Framework Redistributable.  Building content at run time (which could be used for things like level editors and game modding engines) is only supported when XNA Game Studio has been installed on the Windows-based development computer.

Behind the scenes details if you are interested

If you are interested in more details, you can see the data files for the XNA Framework Redistributable 3.0 bootstrapper package by looking at the folder %ProgramFiles%\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages\XnaFxRedist30 on a system with XNA Game Studio 3.0 installed.  We created this bootstrapper package by using the steps in this MSDN document about creating custom bootstrapper packages.

Summary

Windows game packaging and deployment have been consistent pain points since the first version of XNA Game Studio Express.  Hopefully the features that we've added in the XNA Game Studio 3.0 beta will end up being useful in making this process simpler and less error prone.  If you are creating Windows games using XNA Game Studio, I encourage you to try out these features in the 3.0 beta and let us know if you run into any troubles using these features and/or have any suggestions for further improvements by posting on the forums and/or reporting bugs on the Connect site.

<update date="9/30/2008"> Clarified that adding project output from a game project or a content project into a setup/deployment project will not work in XNA Game Studio 3.0. Instead, if you plan to use a setup/deployment project, you have to manually add the game binaries and content files to the setu project one-by-one. </update>

<update date="10/20/2008"> Added a note about networking and content building scenarios that are supported on systems that have XNA Game Studio installed, but not on systems that only have the XNA Framework Redistributable installed. </update>

<update date="11/3/2008"> Added a caveat that this information is only applicable in the XNA Game Studio 3.0 beta, and added a link to the updated blog post that I wrote about Windows game deployment in the final release of XNA Game Studio 3.0. </update>

Comments

  • Anonymous
    September 18, 2008
    Great post. I've been vocal about what a pain point the lack of good setup guidance was, so I'll be similarly vocal about how helpful this post is. :)

  • Anonymous
    September 20, 2008
    With the release of the XNA Game Studio 3.0 beta, some of my colleagues have started posting information

  • Anonymous
    September 30, 2008
    I followed your directions exactly on your blog, I even created a brand new solution with just the cornflower blue, still the same problem.  I tried this at work and and home so its not computer or install related.  I am using visual studio 2008.   I get the warning from your blog Warning 1 No 'HomeSite' attribute has been provided for 'Microsoft XNA Framework Redistributable 3.0', so the package will be published to the same location as the bootstrapper. C:UserschadDocumentsVisual Studio 2008ProjectsTestInstallSetup1Setup1.vdproj Setup1 But then I also get from my error list tab Error 2 Could not find file 'C:UserschadDocumentsVisual Studio 2008ProjectsTestInstallTestInstallContentobjx86DebugContent.dll' 'The system cannot find the file specified.' C:UserschadDocumentsVisual Studio 2008ProjectsTestInstallSetup1Setup1.vdproj Setup1 Error described a little different from the Output tab ERROR: Could not find file 'C:UserschadDocumentsVisual Studio 2008ProjectsTestInstallTestInstallContentobjx86DebugContent.pdb' 'The system cannot find the file specified.' When I create my setup project, I go to Setup > add > project output > Primary Output > OK.  Which with cornflower blue project should be all I need.  Let me know whats up, probably just a beta bug that was missed.

  • Anonymous
    September 30, 2008
    Hi Cpyburn78 - I can reproduce this error on my system as well, but this is not a supported scenario for XNA Game Studio 3.0.  The way I am able to get into this error state is by selecting the primary output from the content project (which is the one selected by default when you right-click on your setup project and choose Add | Project output... | Primary output). An XNA Game Studio content project does not have traditional binary output like a C# project, but it still appears in the Add Project Output Group dialog for a setup project in VS.  You can select your game project in the Project dropdown in the Add Project Output Group dialog, and that will add the binary output of your game project to the MSI that is built and will not result in any build errors.  However, doing that will not automatically add the output of the content project to your MSI so you will still need to manually populate your MSI with the content needed by your game at run time. In XNA Game Studio 3.0, the supported way of getting the content project output automatically added is to use ClickOnce as opposed to a setup project.  That is why the instructions in my blog post say "Use the designers to populate the project with the payload of your game (content plus game binaries)." instead of saying that you should use the Add Project Output Group dialog.  I will update the text of that blog post to be more clear for the future. Also, note that the behavior you are seeing for a setup/deployment project in this scenario is no different than it was in XNA Game Studio 2.0.  We made a decision to invest in improvements in the ClickOnce packaging scenario and integration into the Visual Studio bootstrapper creation process in XNA Game Studio 3.0, but did not have the necessary resources to also improve the setup/deployment project scenario.

  • Anonymous
    October 02, 2008
    The comment has been removed

  • Anonymous
    October 07, 2008
    Last week we had to bid farewell to Charles Cox , content producer and all-around swell guy. Thankfully,

  • Anonymous
    October 08, 2008
    Hy Cpyburn78 - I'm sorry for the delay, I've been on vacation for a little while. When using ClickOnce, the Content directory will be deployed to the same path as your game EXE.  Instead of trying to build a relative or full path like that, could you try to do something like the following:

  1.  Retrieve the path of the EXE while it is running by using reflection (Assembly.GetExecutingAssembly or something like that)
  2.  Remove the name of the EXE from the path
  3.  Append a Content subdirectory name
  4.  Use this path to retrieve your content files Hopefully this helps.

  • Anonymous
    October 15, 2008
    I have been trying to use Clickonce to create a setup package for a GS3 windows game. The created set up fails to include xnafxredist30 that you mention in your article. I retried several times. Any idea why this might not be getting included? It does not appear on the list of pre-requisites I can choose to add either. As far as I am aware I installed GS3 beta in the usual way. Any URL you could point me to that could resolve this would be very helpful. Further to this last I went looking in C:Program FilesMicrosoft SDKsWindowsv6.0ABootstrapperPackages and there is no sub-folder for xnafxredist30. This is presumably why it doesn't appeart on list of pre-requisites to add. And possibly why its not included in the first place. Any idea why it might be missing from this folder? Am I right in thinking it should have been installed when I installed the GS3 beta?

  • Anonymous
    October 15, 2008
    Hi dorchester_software - If you are using the beta version of XNA Game Studio 3.0, there should be a bootstrapper package for the XNA Framework Redistributable 3.0 installed to the folder %ProgramFiles%Microsoft SDKsWindowsv6.0aBootstrapperPackagesXnaFxRedist30.  If it is not in that folder, that is why it doesn't appear in the UI in Visual Studio and doesn't get included when you use ClickOnce to deploy your game. I've got a couple of follow-up questions for you:

  1.  Can you confirm that you have the XNA Game Studio 3.0 beta installed and not the CTP?
  2.  If so, what edition(s) of Visual Studio do you have installed?
  3.  Do you have the following registry value on your system, and if so, what is it set to: [HKEY_LOCAL_MACHINESOFTWAREMicrosoftGenericBootstrapper3.5] Path
  4.  Can you post the following setup log file from your system to a file server so I can take a look:  %temp%XNA Game Studio 3.0 SetupLogsredists*.log

  • Anonymous
    October 15, 2008
    Ah! Perhaps it is the CTP I have installed! Would that explain why I don't have xnafxredist30? If so I will just wait for the 30th October release of GS3, and I'm thinking I'll be sorted. Thanks!

  • Anonymous
    October 15, 2008
    Hi dorchester_software - Yes, if you have the CTP, you won't have any ClickOnce packages for the XNA Framework Redistributable 3.0.  ClickOnce integration was not added to XNA Game Studio 3.0 until the beta.  If you would like, you can try this functionality out in the current beta (see http://go.microsoft.com/fwlink/?LinkId=121507 for install information).  Alternatively, you can wait for the final release of the XNA Game Studio 3.0 on October 30th.

  • Anonymous
    October 20, 2008
    PingBack from http://www.igrophile.com/aaron-stebners-weblog-clickonce-publishing-integration-and/

  • Anonymous
    October 22, 2008
    XNA Game Studio 3.0 に追加した新しい機能の一つに、 XNA Framework ベースの Windows ゲーム向けの機能 ClickOnce パブリッシングがあります。 Aaron

  • Anonymous
    October 31, 2008
    When the XNA Game Studio 3.0 beta was released a couple of months ago, I wrote a blog post describing

  • Anonymous
    November 02, 2008
    The comment has been removed

  • Anonymous
    November 02, 2008
    Hi Deviruchi - The issue here is that Visual Studio is computing the full path, but only listing the relative path in the error message.  This is likely caused by the depth of the directory that your project files are located in combined with the ClickOnce publishing output directory names. Also, it looks like you posted the same question on the Creators Club forums, and one of our developers (Stephen Styrchak) explained what is happening behind the scenes in more detail, and also provided some suggestions for working around this (the easiest thing to try would be to move your VS solution and project files to a folder with a shorter full path). Can you please take a look at his reply on your forum post at http://forums.xna.com/forums/p/19211/100105.aspx#100105 and see if it helps you here?

  • Anonymous
    November 02, 2008
    Thanks Aaron. I hadn't received an email notification and thus missed Stephen's reply on the creators club forum. I appreciate the response here; apologies for the accidental cross-post..

  • Anonymous
    November 02, 2008
    Hi Deviruchi - The Creators Club site was down for a day or so last week for upgrades, so it could have affected the email notifications.  Please let me know if Stephen's suggestions are helpful for you either here via a comment or on the forums via a reply on that thread.