Getting Started

<Preliminary>
Until the project is officially released, you have to create your own NuGet feed that contains the Saltarelle packages. To do this, follow the build instructions in the readme, or download the packages from http://teamcity.codebetter.com/viewLog.html?buildId=lastSuccessful&buildTypeId=bt720&tab=artifacts and then add the directory containing the .nupkg files as a package source (Tools / Options / Package Manager / Package Sources).
</Preliminary>

This getting started guide assumes that you have Visual Studio 2010, NuGet and Asp.net MVC 3 installed.

Creating the projects

To produce any usable output, you will need two projects. First create a new Asp.net MVC3 Web Application, call it WebProject. Use the Razor view engine and the Internet application template. Then create a regular class library project. Call it ScriptProject.

Make it a script project

Now it is time to transform the normal class library (ScriptProject) to a project that will compile to JavaScript. Open the package manager console (preliminary: make sure that your own Saltarelle feed is selected as the package source), make sure that ScriptProject is selected as the default project and type

Install-Package Saltarelle.Compiler

After this completes, your project uses the Saltarelle compiler whenever you build it (if you unload the project and open the .csproj you can see that the usual <Import Project="Microsoft.CSharp.targets"/> has been replaced with <Import Project="Saltarelle.Compiler.targets"/>). During installation it also removed all existing references since those will not work anymore.

If you try to compile it, you will get a lot of errors complaining about predefined types not being defined. That is because we haven't yet added a reference to our runtime library. To do that, go to the package manager console (ensure the correct source and project are selected) and type

Install-Package Saltarelle.Runtime

This will add a reference to the Saltarelle custom mscorlib to your project. It works immediately, but due to a Visual Studio bug you need to unload and reload the project before the reference is visible in the UI. If you try to compile it now you will have a lot fewer errors, all of them concerning things that don't exist in the Saltarelle runtime (namespaces System.Text and System.Linq, and perhaps a few assembly attributes). Remove everything it complains about and compile. If you now go to the output folder (bin\Debug), you should see a file called ScriptProject.js. This is your compiled script, take a look at it!

So now we can compile our project, but we can't yet communicate with the outside world (aside from using 'dynamic' everywhere, but if we wanted to do that we would just write the script directly). To enable that we need to install the import library for the browser object model (in the package manager):

Install-Package Saltarelle.Web

and since only fools write dynamic web sites without jQuery, we want that, too:

Install-Package Saltarelle.jQuery

Now we have everything we need to start compiling to script. (and, yes, the dependencies are set up correctly so in the future you need just install the jQuery package, which will install everything else).

Making it actually do something

So, now that we can make it compile, we should be able to make it do something. This example will be very stupid and 100 times easier to to by just writing the script directly in the page, but this is just a getting started guide.

So, delete everything from Class1.cs and paste in this instead:

using System;
using System.Collections.Generic;
using jQueryApi;

namespace ScriptProject {
	public class Class1 {
		void Run() {
			jQuery.Select("#main h2").Click(evt => jQuery.Select("#main p").FadeToggle());
		}

		static Class1() {
			jQuery.OnDocumentReady(() => new Class1().Run());
		}
	}
}

After doing this, spend some time in the editor and hit Ctrl+space and all other shortcuts you love to use. They all work! (the only thing that doesn't, unfortunately, is that ReSharper 6 complains about all built-in types; they have promised that this is fixed in R#7).

Now we want the script to be usable from the web application, so set up a post-build task (in the ScriptProject project):

copy "$(TargetDir)$(TargetName).js" "$(SolutionDir)\WebProject\Scripts"

If you feel really ambitious, you can also set up a project dependency so the WebProject depends on the ScriptProject, which will ensure that the file is always up to date.

Now it is time to turn to the web application. First, we need to include the runtime library, which we find at $(SolutionDir)\packages\Saltarelle.Runtime.x.y.z. It has both debug and release versions, for now we'll use the debug version so copy mscorlib.debug.dll to the Scripts folder in your web application project. While you're at it, also include ScriptProject.js in the project.

Now go to Views\Shared_Layout.cshtml and insert these script includes:

<script src="@Url.Content("~/Scripts/mscorlib.debug.js")" type="text/javascript"></script>
<script src="@Url.Content("~/Scripts/ScriptProject.js")" type="text/javascript"></script>

Run the application, click the header and watch the text below it fade in and out.

Congratulations, you have just compiled your first C# to JavaScript!