Jeremy Kuhne's Blog : MSBuild

Creating a SSCLI C# Template for Visual Studio

jkuhne — Sat, 23 Feb 2008 08:29:00 GMT

In my last post (MSBuild your SSCLI C# projects) I demonstrated how to create an MSBuild targets file for the SSCLI (Rotor). In this post I'll show you how to make it easier to use Visual Studio to develop SSCLI C# projects.

To build successfully in VS you need to do a few things, notably:

Override assembly resolution so the SSCLI assemblies are targeted (the last post shows you how to do this)
Change the startup action for the project to "Start external program" (in the Debug property page for the project)
Enter the path for clix.exe as the startup program
Put the output binary for you application in as the "Command line arguments"

It's a little tedious to set all of this up by hand. Thankfully it ends up it's pretty easy to make a template to do most of the dirty work. With a small additional change to the targets file it makes it completely painless. (Well, with the one major caveat that you can't debug managed SSCLI code with VS.)

The existing templates are in the VS folder under "Common7\IDE\ProjectTemplates". Each of the templates are stored in a zip file- perusing a few of these in addition to looking at the documentation will get you up to speed in no time. As such I'm not going to give a tutorial here, I'm just going to talk briefly about what I did to create my template and share it with you.

I started with the "CSharp\Windows\1033\ConsoleApplication.zip" because I wanted the equivalent of that for SSCLI. I had to make most of the changes to the .vstemplate file and a few changes to the .csproj file to link in my targets. Here is what my .vstemplate file looks like:

<?xml version="1.0" encoding="utf-8"?>

<Name>SSCLI Console Application</Name>

<Description>Console Application for the SSCLI (Rotor) Framework</Description>

<Icon>SSCLIConsole.ico</Icon>

<TemplateID>SSCLI.CSharp.ConsoleApplication</TemplateID>

<ProjectType>CSharp</ProjectType>

<DefaultName>SSCLIConsoleApplication</DefaultName>

</TemplateData>

<ProjectItem ReplaceParameters="true" TargetFileName="Properties\AssemblyInfo.cs">AssemblyInfo.cs</ProjectItem>

<ProjectItem ReplaceParameters="true" OpenInEditor="true">Program.cs</ProjectItem>

</Project>

</TemplateContent>

</VSTemplate>

Not too hard to wrap your head around. In the .csproj I changed the import to

<Import Project="$(MSBuildToolsPath)\SSCLI.CSharp.targets" />

Zipped up with a custom icon (had to try it) I dumped it in my "Documents\Visual Studio 2008\Templates\ProjectTemplates\Visual C#" folder, created a few projects off the template to tweak it out and I was almost done.

The other bit that I've already mentioned was setting the project properties to run "clix". Figuring this bit out isn't too terribly straightforward. VS project settings that don't go into the .csproj go into a ".csproj.user" file that is created alongside your .csproj whenever you change the defaults. Change the defaults to create said file and you'll quickly discover what you need to set in your .targets file to establish your own defaults. (Note that these properties are listed in the Microsoft.Build.Commontypes.xsd, found in the MSBuild directory in your relevant framework directory. Also note that it doesn't contain valid values for the VS properties.)

Here is what I added to SSCLI.CSharp.targets (which should live in your MSBuild directory):

<StartAction>Program</StartAction>

<StartProgram>$(SSCLI_FrameworkPath)\clix.exe</StartProgram>

<StartArguments>$(TargetFileName)</StartArguments>

</PropertyGroup>

That's pretty much it. Now you can relatively easily create SSCLI projects. You don't get managed debugging, as mentioned. You do get the rest of the development enviroment benefits however (intellisense, etc.).

The complete SSCLI.CSharp.targets file can be found here. The template can be found here.

MSBuild your SSCLI C# projects

jkuhne — Wed, 20 Feb 2008 09:21:00 GMT

[ Edit 22 Feb 2008: The complete SSCLI.CSharp.targets file can be found here. ]

In my last post I got SSCLI compiling with the 2008 C++ compiler (SSCLI 2.0 and Visual Studio 2008). (A side note: since it is clearly possible to build SSCLI with the compiler there is no reason you shouldn't be able to get a VS Solution up and running that would build the SSCLI- just a lot of work.) Having done that I thought it would be interesting to see how plausible actually working in VS with SSCLI projects would be.

As a first step, it ends up that there is relatively little you have to do to get a .csproj that will work with SSCLI through MSBuild. The key items are:

Set the Csc.exe path.
Make sure the TargetFrameworkDirectory gets set to the SSCLI output directory.

The way to figure this out is to work backwards from the compiler (csc.exe). Look at what csc's arguments are and look for where arguments get generated for it in the build targets.

Microsoft.CSharp.targets is the file to start looking in. It is included at the end of a .csproj so this is a pretty logical place to start looking. Thankfully the file is short, so it is relatively easy to digest. (The target files are in the Windows\Microsoft.Net\Framework\v0.0 directories. I used 3.5 for this article- the last set of MSBuild targets before this version are in 2.0.50727.)

The <Csc> task in Microsoft.CSharp.Targets has a "ToolPath" argument that takes $(CscToolPath). There is #1! Finding #2 begins with "References" which is set to @(ReferencePath). You won't find much in Microsoft.CSharp.Targets so you need to look to the included Microsoft.Common.Targets.

You can figure out #2 by looking at the generation of @(ReferencePaths). Doing a search will drop you in the ResolveAssemblyReferences target- it's in the comments as an [OUT] -- bingo. In a csproj referenced .NET assemblies are listed under (logically) <Reference> items. These are listed here as an [IN] in the comments - see the connection? (Note: the quick way to look for usage of items is to search for '@(ItemName' -- don't use the closing parenthesis as you'll miss transforms.)

In this target the simple "System" <Reference> is turned into a full @(ReferencePaths) item. If you look at the <ResolveAssemblyReference> task within this target you'll see some promising parameters-- the most promising being SearchPaths="$(AssemblySearchPaths)". Look for the source of $(AsemblySearchPaths) and you'll find a nice detailed comment at the top of Common.Targets:

<!--

The SearchPaths property is set to find assemblies in the following order:

(1) Files from current project - indicated by {CandidateAssemblyFiles}

(2) $(ReferencePath) - the reference path property, which comes from the .USER file.

(3) The hintpath from the referenced item itself, indicated by {HintPathFromItem}.

(4) The directory of MSBuild's "target" runtime from GetFrameworkPath.

The "target" runtime folder is the folder of the runtime that MSBuild is a part of.

(5) Registered assembly folders, indicated by {Registry:*,*,*}

(6) Legacy registered assembly folders, indicated by {AssemblyFolders}

(7) Look in the application's output folder (like bin\debug)

(8) Resolve to the GAC.

(9) Treat the reference's Include as if it were a real file name.

-->

{CandidateAssemblyFiles};

$(ReferencePath);

{HintPathFromItem};

{TargetFrameworkDirectory};

{Registry:$(FrameworkRegistryBase),$(TargetFrameworkVersion),$(AssemblyFoldersSuffix)$(AssemblyFoldersExConditions)};

{AssemblyFolders};

{GAC};

{RawFileName};

$(OutDir)

</AssemblySearchPaths>

{TargetFrameworkDirectory} is key here. If you search for "TargetFrameworkDirectory" you'll find the property shows up in the GetFrameworkPaths and GetReferenceAssemblyPaths targets. It is the one we want. It gets replaced by $(TargetFrameworkDirectory) inside of the <ResolveAssemblyReference> task. You can see this if you use Reflector to look at the task-- but you can probably make that leap without digging further.

That gives us everything we need. We know where all of our framework (SSCLI) assemblies are so we just need to override Common.targets' path building completely for this and inject our overrides into the regular targets. You can do this by creating a new target file that includes the Microsoft.CSharp.targets and use this new file instead in your .csproj. Here's the answer:

<SSCLI_FrameworkPath>$(ROTOR_DIR)\binaries.x86chk.rotor</SSCLI_FrameworkPath>

<CscToolPath>$(SSCLI_FrameworkPath)</CscToolPath>

<TargetFrameworkDirectory>$(SSCLI_FrameworkPath)</TargetFrameworkDirectory>

</PropertyGroup>

<Target

Name="SSCLI_InitialChecks">

<Error

Condition=" '$(ROTOR_DIR)' == '' "

Text="ROTOR_DIR is not set. Please set an environment variable or property to the SSCLI directory. Note that running 'env' in your SSCLI directory will set this."/>

<Error

Condition="!Exists('$(SSCLI_FrameworkPath)')"

Text="SSCLI not found at expected path: '$(SSCLI_FrameworkPath)' Please build SSCLI if necessary." />

</Target>

<!--

Override Microsoft.Common.targets GetFrameworkPaths

-->

<Target

Name="GetFrameworkPaths"

DependsOnTargets="$(GetFrameworkPathsDependsOn)" />

<!--

Override Microsoft.Common.targets GetFrameworkPaths

-->

<Target

Name="GetReferenceAssemblyPaths"

DependsOnTargets="$(GetReferenceAssemblyPathsDependsOn)" />

</Project>

Dump the xml above into a file (say, called "SSCLI.CSharp.targets"), drop it in the same directory as the other target files, and (as already stated) include this file in your csproj instead of Microsoft.CSharp.targets.

Now you can 'msbuild myNiftySscliApp.csproj'. And yes, you can even open said csproj in Visual Studio and do some developin'. (With the sad lack of managed debugging, but, hey-- you get Intellisense and all of the other goodies of the IDE.) In my next posts I'll show you how to grease the wheels as much as you can with the IDE, starting with how to build and run easily, then moving on to making an SSCLI project template.