Projects and Visual Studio¶

The project file¶

An app is a Silverlight 3 class library that imports the SDK's targets instead of Silverlight's:

<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <Configuration Condition=" '$(Configuration)' == '' ">Release</Configuration>
    <OutputType>Library</OutputType>
    <AssemblyName>MyApp</AssemblyName>
    <RootNamespace>MyApp</RootNamespace>
    <SilverlightAppEntry>MyApp.App</SilverlightAppEntry>
    <OutputPath>bin\$(Configuration)\</OutputPath>
  </PropertyGroup>
  <ItemGroup>
    <Reference Include="mscorlib" />
    <Reference Include="System" />
    <Reference Include="System.Core" />
    <Reference Include="System.Windows" />
    <Reference Include="System.Windows.Controls.Navigation" />  <!-- pages and Frame -->
    <Reference Include="Microsoft.Xbox" />                       <!-- Xbox controls -->
    <Reference Include="Microsoft.Xbox.Core" />                  <!-- XNA basics, PlayerIndex -->
    <Reference Include="Microsoft.Xbox.Services" />              <!-- gamer services -->
    <Reference Include="Microsoft.Xbox.Storage" />              <!-- storage and cache containers -->
  </ItemGroup>
  <ItemGroup>
    <ApplicationDefinition Include="App.xaml"><Generator>MSBuild:Compile</Generator></ApplicationDefinition>
    <Page Include="MainPage.xaml"><Generator>MSBuild:Compile</Generator></Page>
    <Compile Include="App.xaml.cs"><DependentUpon>App.xaml</DependentUpon></Compile>
    <Compile Include="MainPage.xaml.cs"><DependentUpon>MainPage.xaml</DependentUpon></Compile>
  </ItemGroup>
  <Import Project="path\to\Silverlight360\msbuild\XboxSilverlight.targets" />
</Project>

A project in a repository of its own can find the SDK through a property, so nobody's paths end up in the project file:

<PropertyGroup>
  <Silverlight360Dir Condition="'$(Silverlight360Dir)' == ''">$(SILVERLIGHT360)</Silverlight360Dir>
  <Silverlight360Dir Condition="'$(Silverlight360Dir)' == ''">$(MSBuildThisFileDirectory)..\Silverlight360\</Silverlight360Dir>
  <Silverlight360Dir Condition="!HasTrailingSlash('$(Silverlight360Dir)')">$(Silverlight360Dir)\</Silverlight360Dir>
</PropertyGroup>
<Import Project="$(Silverlight360Dir)msbuild\XboxSilverlight.targets" />

That takes /p:Silverlight360Dir=..., else the SILVERLIGHT360 environment variable, else a clone next to the repository. tools\Build-XboxApp.ps1 builds such projects too.

References name assemblies only. The SDK resolves them from the runtime profile's reference folder, never from desktop Silverlight, so the Xbox additions (UIElement.GamePadButtonDown, Application.Shutdown, ...) are there to compile against.

Available assemblies:

Assembly	What's in it
`mscorlib`, `System`, `System.Core`, `System.Net`, `System.Xml`	The .NET base, with Xbox additions (see the reference). `System.Core` has LINQ, `Action<T1,T2>` and `Func<>`.
`System.Windows`	Silverlight 3 UI, plus controller input, media commands and the Xbox `MediaElement` and `Button` additions.
`System.Windows.Controls.Navigation`	`Frame`, `Page`, `NavigationService`.
`System.Xml.Linq`	LINQ to XML.
`System.Windows.Interactivity`	Blend behaviors and triggers.
`Microsoft.Xbox`	Xbox controls (`XboxApplicationFrame`, `Pivot`, `Rune`, `Legend`, `MediaTransport`, ...), Kinect, speech, SmartGlass, transitions.
`Microsoft.Xbox.Core`	XNA framework basics: `PlayerIndex`, math types, `FrameworkDispatcher`, sound effects.
`Microsoft.Xbox.Services`	XNA gamer services: signed-in gamers, the Guide, presence, XAuth tokens.
`Microsoft.Xbox.Storage`	XNA storage: `StorageDevice`, `StorageContainer`, `CacheContainer`.
`Microsoft.Web.Media.SmoothStreaming`	The Smooth Streaming player.

Build properties¶

Property	Default
`XboxRuntimeProfile`	`runtime\plex-2015`	Profile to compile against and package with; one made with `-KeepTitle` for an app that needs a title (The app's title).
`XboxPackageDir`	`bin\<Configuration>\xbox\`, or `bin\<Configuration>\app\` with `XboxAppOnly`	Package output.
`XboxAppOnly`	`false`	`true` writes the app's own files alone, without the runtime: see Handing out an app. `Build-XboxApp.ps1 -AppOnly` sets it.
`XboxSplashScreen`, `XboxSplashScreen480`	`templates\*.jpg`	1280x720 and 640x480 JPEG splash screens.

What goes into the package¶

The core framework (mscorlib, System, System.Core, System.Net, System.Windows, System.Windows.RuntimeHost, System.Xml) comes with the runtime and isn't listed in the app's manifest. Every other library, the Xbox ones included, is copied next to your assembly and listed in AppManifest.xaml, the way the shipped apps do it. XAML can only resolve types from assemblies the manifest lists: a page using xbox:Pivot fails to load with a XamlParseException (error 2255) if Microsoft.Xbox isn't there.

bin\Release\xbox\
  default.xex                  the host (XamlHost), from the profile
  xcoreclr.dll agcore.dll npctrl.dll ...   the runtime, from the profile
  *.dll *.ni.dll ...           framework assemblies and native images, from the profile
  AppManifest.xaml             generated: entry point and assembly parts
  XboxAppManifest.xml          resolutions and splash screens
  SplashScreenImage.jpg  SplashScreenImage480.jpg
  MyApp.dll                    your code (IL)

Your assemblies stay IL; the platform's CLR compiles them when they load. Native images aren't needed, but Build-XboxApp.ps1 makes them after the build so the code runs compiled; -NoNGen leaves them out (Native images).

Handing out an app¶

Most of a package is the runtime profile's: Microsoft's runtime and framework assemblies, and the donor app's default.xex. They aren't yours to hand out. Build with XboxAppOnly for the app's own files alone:

.\tools\Build-XboxApp.ps1 -Project path\to\MyApp.csproj -AppOnly

bin\Release\app\
  AppManifest.xaml  XboxAppManifest.xml
  SplashScreenImage.jpg  SplashScreenImage480.jpg
  MyApp.dll                    your code, and libraries you bring
  MyApp.ni.dll                 its native image (none with -NoNGen)
  ...                          your content

The framework libraries an app copies from the profile's reference folder, such as Microsoft.Xbox and System.Xml.Linq, are left out too: the runtime package has the same files. Whoever installs the app makes a runtime profile from an app of their own, copies its package folder to the console, and copies the app's files over it. The native images load only when that app is the same donor app as your profile's (the build says which); for any other, build with -NoNGen (Native images). Silverdash360 publishes its releases this way, with tools/Release.ps1, and its installation guide takes its users through the steps.

Language¶

C# 3 and Silverlight 3, with what the Xbox runtime adds on top. XAML can't use x:String; declare xmlns:sys="clr-namespace:System;assembly=mscorlib" and use sys:String. Dispatcher.BeginInvoke takes a Delegate, so anonymous methods need a cast: Dispatcher.BeginInvoke((Action)delegate { ... }), or reference System.Core and pass a lambda.

The class library is Silverlight 3's, so some things desktop .NET and later Silverlight versions have are missing. The compiler reports them, but the usual replacements are:

Missing	Use
`HashSet<T>`	`Dictionary<T, bool>`, or LINQ's `Distinct` and `Contains`
`List<T>.FindIndex`, `Find`, `RemoveAll`	a loop, or LINQ
`TextBlock.TextTrimming`	a fixed width with `TextWrapping="NoWrap"`; the text is clipped
`Tuple`	a small class
`Marshal.AllocHGlobal`	a pinned array (see Native code)

Visual Studio¶

The projects have no Silverlight project type GUID, so Visual Studio opens them as plain C# projects. MSBuild 14 and the MSBuild of Visual Studio 2022 and 2026 build them unchanged, as long as the Silverlight 3 SDK is installed. Building from the IDE produces the same bin\Release\xbox package.

IntelliSense¶

Visual Studio shows IntelliSense text for a referenced assembly from an <Assembly>.xml next to it. tools\Install-ApiDocs.ps1 writes those files into the profile's reference folder. Each member's text comes from the first of these that documents it:

The SDK's own documentation (docs\api\*.xml): every Xbox-specific type and member, and the Xbox additions to the standard assemblies.
Documentation already installed on your machine for the APIs the platform shares with them: the Silverlight 3 and 4 SDKs, the .NET Framework reference assemblies, and XNA Game Studio 4.
Standard patterns: dependency property identifiers, default constructors, standard overrides.

The script prints how much of each assembly is documented. With Silverlight 3 and XNA Game Studio 4 installed, every public member of every assembly in the default profile is covered.

The installed files are copied into the profile only. The profile stays local like the rest of it, so nothing of Microsoft's is redistributed.

To check the SDK's files after editing them:

.\tools\Test-ApiDocs.ps1

It reports unknown member IDs, parameter names that don't match, missing summaries and cref links that don't resolve. tools\new_api_reference.py regenerates the Markdown API reference from the same files.