Script# works by compiling C# source code and files directly into a single JavaScript file, in much the same way as the C# compiler that generates MSIL into a single assembly.
The inputs into the C# compiler are your source files, and any referenced assemblies. The referenced assemblies represent either script APIs in existing script files written manually, or script APIs defined within another Script# project with a corresponding generated script file. The regular C# compiler is used to produce an assembly for your code (that can then be referenced by another project) and the XML doc-comments file that can then be used to produce documentation. The Script# compiler on the other hand generates a .js script file. All the script files - existing and generated – can then be deployed into a Web site or Web application running on any platform for use at runtime without any Script# dependency.
During compilation, the C# compiler and Script# compiler together provide build-time type checking and validation of your code. This helps catch typos and other common script errors at build-time on the development machine as opposed to at runtime on the end-user's machine.
The Script# compiler produces both release and debug versions of your script. The release version is minimized by removing whitespace and by reducing identifier lengths for internal and private members with shorter names. The debug version is formatted for readability and debuggability.
The Script# System
Logically speaking there are three layers to the Script# system: the compiler, the core runtime and the framework.
Script# Compiler - The compiler compiles C# code into JavaScript, and is only needed on the development or build machine. The compiler assumes the existence of APIs defined in the Script# core runtime to represent classes and other OOP constructs defined in the originating C# source code.
Script# Runtime - At development time, the runtime provides the equivalent of mscorlib.dll. It defines various key .NET types such as System.Object, primitive types and other core BCL types needed to author and compile C# source code. At runtime, the core runtime is a small bootstrapper script file that implements how various OOP constructs are defined and simulated in JavaScript, as well as providing basic extensions to existing JavaScript objects to implement functionality expected by .NET developers. The default Script# runtime is implemented in sscorlib.dll and its accompanying runtime counterpart sscorlib.js. To use Microsoft ASP.NET Ajax, the equivalent pair consists of aacorlib.dll and MicrosoftAjax.js as its runtime counterpart.
Runtime assemblies shipping with Script# representing other script APIs such as Virtual Earth, RSS Feeds etc. ship in assemblies named ss*.dll.
Script# Framework - The framework is completely optional. The choice of framework also depends on the application and the developer. The compiler itself is not bound or dependent in any way against any particular framework choice. The default ScriptFX framework accompanying Script# ships in assemblies and scripts named ssfx.*.dll and ssfx.*.js.
The specific runtime assemblies and framework assemblies are described in the topic on What's in Script#.
Using Script#
Script# can be used either via the command-line (ssc.exe; use ssc.exe -? for additional help) or via MSBuild (via a custom task added to your .csproj profile file). The MSBuild approach is recommended.
Furthermore, when you install Script#, a set of project templates are added to Visual Studio. It is highly recommend you start your projects using these templates, as they have been setup correctly to use the Script# runtime assembly (sscorlib.dll) instead of the default .NET runtime assembly (mscorlib.dll) using the compiler’s /nostdlib option.
You can add references to Script# assemblies using the regular reference feature in MSBuild projects or from within Visual Studio. Note that you cannot reference regular .NET assemblies as those cannot be ported into script.
Limitations
C# Limitations
Script# is not intended to convert arbitrary C# applications into script. It also does not provide a full implementation of the .NET framework or the CLR within the browser, as that would be impractical. Script# targets the C# 2.0 language with some unsupported constructs that do not make sense in script, or could not be implemented due to lack of resources.
The idea is that Script# is very much about script development, rather than porting .NET code. As such most of the limitations listed below for completeness have little impact on real Ajax scenarios. The following C# constructs are unsupported:
- Global non-namespaced types and nested types
- Nested namespace declarations; instead you must declare the whole namespace name in a single namespace statement.
- The “System” namespace can only be used to represent existing script types and APIs and not be used for any C# code that will be compiled into script.
- The set of reserved words that cannot be used in Script# include not only C# reserved words, but also JavaScript reserved words.
- Struct types are disallowd as script does not offer value type semantics.
- Pointer types are also disallowd.
- Overloading is limited to providing alternate signatures, rather than multiple implementations for the same named member.
- Destructors, operators methods and conversion methods are unsupported.
- Enumeration fields must have explicit values defined, even if they are the default (0, 1, 2, ...)
- Set-only properties are unsupported.
- The “new” modifier on members is unsupported.
- Throw statements must always throw an explicit object.
- Unsupported statements include goto, using, lock/unlock and yield.
- Unsupported expressions include sizeof, fixed, stackalloc, and default.
The following are limitations in the current compiler implementation:
- Generics
- Support for ref, out and params modifiers on parameters
- Ability to specify a type using its namespace-qualified type names; instead as a workaround you can uses aliases (eg. using Foo = SomeNamespace.SomeType) if you need to disambiguate between conflicting types.
JavaScript Limitations
Script# provides support for the majority of script constructs needed for real-world applications and frameworks. It does however have some small limitations:
- Limited uses of closures - Closures can be modeled to a certain extent using anonymous delegates in C#. However closures used to define classes are not supported. Instead the Script# compiler generates classes based on the prototype pattern.
- Identifier characters cannot contain "$" - This is not supported in C# source code. The compiler uses this limitation stemming from C# rules to its advantage by using “$” in generated identifier names to ensure they do not conflict with existing identifiers elsewhere in your code.
A more in-depth list of how C# constructs are mapped to JavaScript is described on the topic From C# to Script. On the flip side, an in-depth list of how script constructs are modeled in C# is described on the topic Achieving Script’isms in C#.
