Migrated documents from aspclassiccompiler.codeplex.com

docs/Acknowledgements.md

@@ -0,0 +1,3 @@
+This project uses:
+* [Microsoft Dynamic Language Runtime](http://www.codeplex.com/dlr)
+* The VBScript Parser was adapted from [Paul Vick's VBParser](http://www.panopticoncentral.net/archive/2006/03/27/11531.aspx).

docs/Contact.md

@@ -0,0 +1 @@
+For general discussions, please use the project forum. If you have questions just for us, please use the contact user form. You might also visit [http://weblogs.asp.net/lichen/](http://weblogs.asp.net/lichen/) and use the contact user form there. Thanks.

docs/Contributors.md

@@ -0,0 +1,5 @@
+This project needs contributors to be viable. We need contributor of all technical capabilities, from writing a test case, and example, to working on the compiler.
+
+To contribute to the project, go to the "Source Code" tab and click fork. You can then work in your fork. When you are ready to contribute your code, send a pull request. We will review your code and either accept or reject. Please fork once per idea to keep the change small so that it can be reviewed easily. Once you have a few successful contributions, you will be promoted to the Developer role.
+
+This project uses Mercurial source control. Mercurial is thest best solution for open source development today. If you are not familiar with Mercurial, visit [Using Mercurial on Codeplex](http://codeplex.codeplex.com/wikipage?title=Using%20TortoiseHG%20with%20CodePlex) . Be sure to listen to [Rob Conery 's excellent tutorial](http://tekpub.com/codeplex). Also visit [hginit](http://hginit.com/) when you are ready for the next step. Mercurial promotes forking. We will be using workflow similar to [the Orchard Project](http://www.orchardproject.net/docs/Contributing-patches.ashx).

docs/FAQ.md

@@ -0,0 +1,15 @@
+## Which .Net Framework version does the ASP Classic Compiler support?
+We will support .Net Framework 2.0, 3.0, 3.5 and 4.0. Initially, we only support 2.0-3.5. We do not support 4.0 because building the current DLR source code with 4.0 requires a daily build of VS2010 that we cannot obtain. Hopefully, we will be able to supply a copy of ASP Classic Compiler for .Net Framework 4.0 when VS 2010 beta 2 is released.
+
+## What is the status of your project?
+At this time, we have implemented most features in VBScript 3.0 standard. It can [run](http://weblogs.asp.net/lichen/archive/2009/12/20/asp-classic-compiler-0-6-0-released-it-can-run-fmstocks-1-0.aspx) Microsoft end-to-end sample applications like FMStock. Still need to implement VBScript 5.0 features such as Class, Execute and Eval.
+
+## What does the version number mean?
+Before 1.0, we used version numbers to represent the % of work completed to reach 1.0. So version 0.5.1.31188. would mean we are at 51%. The build number 31188 corresponds to the DLR changeset number so that you know the DLR version we are using in case you use other DLR languages in the same AppDomain.
+
+## When are you going to release the 1.0 version?
+We are not able to commit to any schedule yet. We hope to release shortly after VS2010 is released or Dynamic Language Runtime 1.0 is released. We have overcome most major technical challenges but still have lots of loose ends to work on. That said, it is possible to focus our efforts on making some applications run correctly even before the general release. [Contact](Contact) us if you are interested in it.
+
+## There are a huge number of ASP pages out there. How can you be compatible with all of them?
+Compiler writers work at the nuts and bolts level. We are concerned with the behavior of operators, assignments and method calls, etc. as well as all the implicit conversions involved. So we are dealing with a much smaller set of cases. We expect the system to be right if it is right at the nuts and bolts level. That said, to make VBScript.net right is still a huge task without a formal specification. There are many caveats in VBScript. Fortunately, [http://blogs.msdn.com/ericlippert/archive/tags/VBScript/default.aspx](Eric Lippert's blog) provides a lot more information. Some of the behavior is actually [http://blogs.msdn.com/ericlippert/archive/2005/03/23/vbscript-quiz-answers-part-eight.aspx](bugs that could not be fixed). So the answer is that we are not able to be and probably do not want to be 100% backward compatible. We will apply some common sense, encourage good practices and hopefully come out with a compiler that it is compatible with most of the real-world ASP pages. We will break away from some old problems and hopefully can move forward with a cleaner product. We certainly hope we will do much better than any of those ASP code converters on the market because we are not concerned with code readability but rather concerned with syntactic compatibility. Our development is very much spec and test driven at this point.
+

docs/Features.md

@@ -0,0 +1,45 @@
+# Features and Limitations
+
+## VBScript.net compiler features:
+* For 1.0 release, we plan to implement VBScript 4.0 (see [http://msdn.microsoft.com/en-us/library/4y5y7bh5(VS.85).aspx](VBScript Version Information)). Features like defining classes in VBScript and the Eval/Execute/ExecuteGlobal are not implemented, although DLR does allow the implementation of these features. We plan to implement these features in a later release. However, if you would like to make these a higher priority, please vote in the Issue Tracker.
+	* You can still use 5.x Regular Expression features since we are reusing Microsoft VBScript regular expression COM objects through COM interop. However, you must have Microsoft VBScript 5.x installed on your system.
+	* The 5.0 Escape, GetLocal, SetLocal, Timer and Unescape functions are supported.
+* Interop with .net framework
+	* All the types in VBScript.net compiler are natively CLR Types. Please also see [http://msdn.microsoft.com/en-us/library/9e7a57cf(VS.85).aspx](VBScript Data Types). The following are the mappings between the types in VBScript and the CLR types used VBScript.net:
+|| VBScript type || VBScript.net type||
+| Empty | null |
+| Null | System.DbNull |
+| Boolean | System.Boolean |
+| Byte | System.Byte |
+| Integer | System.Int16 |
+| Currency | System.Decimal |
+| Long | System.Int32 |
+| Single | System.Single |
+| Double | System.Double |
+| Date | System.DateTime |
+| String | System.String |
+| Object | System.Object |
+| Variant | System.Object |
+| Error | VBScript.net internal helper object |
+	* Imports statement. Note that the behavior of the Imports statement in VBScript.net is different in VB.NET. See below:
+		* Top namespace import. For example, if you use {{imports System}}, VBScript.net would know that the "System" is a namespace rather than a variable. However, when you use a class, you still have to specify the full namespace, for example, {{ System.Console.WriteLine("Hello World") }}. The reason is we do not do exhaustive searches in all imported namespaces to reduce the compiling time as a scripting language. If you do not want to type the entire namespace, you might use Alias Import.
+		* Alias Import. You might define an alias for a namespace or a class, for example:
+{{
+imports c=System.Console
+c.WriteLine("hello world")
+}}
+
+## VBScript.net compiler limitations
+# Can assign to a constant. This should not happen.
+# Imp and Eqv operators are not implemented. Not sure if anyone uses it. Submit an issue if you need it.
+# LoadPicture function not implemented.
+# There are many other more subtle incompatibilities (such as automatic widening of numeric type) that we have to document separately.
+
+## ASP Classic Compiler Features:
+# Implemented as an asp.net http module. See [Installation](Installation) page for setup and configuration.
+
+## ASP Classic Compiler limitations:
+# Global.asa not supported. If you want to add data to application or session state, use global.asax instead.
+# TypeLibrary declaration using syntax like {{<!--METADATA TYPE="typelib" uuid="00000206-0000-0010-8000-00AA006D2EA4" -->}} is not implemented. Use include file adovbs.inc instead.
+# ASP @ Directives ignored. @TRANSACTION declarative in ASP page is ignored. ASP page runs in a COM+ context. ASP Classic Compiler runs pages in asp.net worker process.
+# COM objects invoked by asp page cannot access built-in asp objects, request, response and session, etc. This is because ASP Classic Compiler does not put these objects into COM+ context. As a result, COM objects like MSWC.BrowserType would not work with ASP Classic Compiler.

docs/History.md

@@ -0,0 +1,76 @@
+* 3/29/2011 - Open the source code. See [Announcements](http://weblogs.asp.net/lichen/archive/2011/03/30/asp-classic-compiler-is-now-open-source.aspx).
+* Change Set 41463 - 4/4/2010 Version 0.6.2.34834  VS2010 and VS2008 Builds.
+# Fixed the bugs regarding unary operation binder and logical binary operation binder reported in this [post](http://aspclassiccompiler.codeplex.com/Thread/View.aspx?ThreadId=205235). 
+# Runtime exception thrown by compiled VBScript can now report the name of the source file and line number if you enable tracing. See this [post](http://weblogs.asp.net/lichen/archive/2010/04/05/how-to-enable-tracing-in-asp-classic-compiler.aspx) on how to enable tracing.
+* Change Set 41199 - 3/27/2010 Version 0.6.1.34834  VS2010 and VS2008 Builds.
+# Fixed worked item 3954.
+# Fixed the bugs reported in this [post](http://aspclassiccompiler.codeplex.com/Thread/View.aspx?ThreadId=205235). 
+# You can now using custom classes in Asp Classic Compiler. See this [post](http://weblogs.asp.net/lichen/archive/2010/03/28/using-custom-net-classes-in-asp-classic-compiler.aspx) for more details.
+* Change Set 33532 - 12/18/2009. Version 0.6.0.34834 VS2010 and VS2008 Builds. (Do not download 33384-33386 as they have build errors)
+# We reached a milestone today. ASP Classic Compiler is working now with a first end-to-end sample application, [Fitch and Mather Stocks 1.0](http://www.microsoft.com/downloads/details.aspx?FamilyID=243abaa0-dd03-4fbc-b58f-5da61839f948&DisplayLang=en).
+# We have included a [preconfigured copy](History_fmstocks10.zip) of Fitch and Mather application for you to try.
+# See [this](http://weblogs.asp.net/lichen/archive/2009/12/20/asp-classic-compiler-0-6-0-released-it-can-run-fmstocks-1-0.aspx) and [this](http://weblogs.asp.net/lichen/archive/2009/12/20/installing-fmstocks-1-0-on-later-platforms.aspx) blog entries for more information.
+* Change Set 32739 - 12/3/2009. Version 0.5.7.34834 VS2010 and VS 2008 Builds. 
+# Fixed the bug in [this discussion](http://aspclassiccompiler.codeplex.com/Thread/View.aspx?ThreadId=76818).
+* Change Set 32557 - 11/30/2009. Version 0.5.6.34834 VS2010 and VS 2008 Builds. Still no Silverlight update.
+# Fixed numerous bugs in the parser and the code generator.
+# Implemented On Error.
+# Allows method redefinition. See this [discussion](http://aspclassiccompiler.codeplex.com/Thread/View.aspx?ThreadId=76620) for more details.
+* Change Set 32030 - 11/16/2009. Version 0.5.5.34834 VS2010 and VS2008 Builds. This release does not have a Silverlight build.
+# Setup the infrastructure to map from generated code back to the source code so that we can report the location accurately in ASP files.
+# If a file has multiple syntax errors, chances are that we are able to report all the errors at once. In contrast, ASP Classic only reports one error at a time. That is because our parser attempts to recover from the error and continue parsing the file. 
+* Change Set 31328 - 11/3/2009. Silverlight samples uploaded. Minor bug fix to ASP include syntax. Visit [this blog](http://weblogs.asp.net/lichen/archive/2009/11/04/uploaded-silverlight-sample-for-vbscript-net-compiler.aspx) for details of the Silverlight sample.
+* Change Set 31281 - 11/2/2009. Version 0.5.4.34834. Built with DLR 0.92. We are going to stay with DLR 0.92 stable build for a while instead of using the weekly build so that we can be compatible with VS2010 beta2.
+# VS2010 build is available now in addition to the VS2008 build.
+# Silverlight build of our VBScript.NET compiler is available for the first time. We will try to come out with samples in the next weekly release.
+# All the binaries are consolidated into the bin folder.
+
+* Change Set 30945 - 10/25/2009. Version 0.5.3.32871. Built with DLR Changeset 32871.
+# Now ASP Classic Compiler would run under medium trust or Windows Azure partial-trust. Partial-trust is the default trust level of Windows Azure. Windows Azure does not support ASP Classic. Windows Azure supports php but requires full-trust. ASP Classic Compiler is the only way to run ASP pages on Azure without changing the trust level.
+# Azure sample uploaded. We modified only one view /home/index.asp but that is enough to prove the concept.
+# Variable initialization in declaration statement as a VBScript extension. For example: Dim s = New System.Text.StringBuilder() 
+# Add the operator overloading through extension methods. C# supports extension methods, but not "extension operators". We added this support so that we can add new behavior without the need to modify our binders. Some typical ASP code would now run much faster by a simple change. For example, ASP pages often have code like:
+{{
+<%
+    Dim s
+    Dim i
+    
+    s = "<table>"
+    For i = 1 To 12
+        s = s + "<tr>"
+        s = s + "<td>" + i + "</td>"
+        s = s + "<td>" + MonthName(i) + "</td>"
+        s = s + "</tr>"
+    Next
+    s = s + "</table>"
+    Response.Write(s)
+
+%>
+}}
+This code is slow because the runtime keeps creating new strings and discarding the old one. Now we just need a simple change:
+{{
+<%
+    Imports System
+    Dim s = New System.Text.StringBuilder()
+    Dim i
+    
+    s = s + "<table>"
+    For i = 1 To 12
+        s = s + "<tr>"
+        s = s + "<td>" + i + "</td>"
+        s = s + "<td>" + MonthName(i) + "</td>"
+        s = s + "</tr>"
+    Next
+    s = s + "</table>"
+    Response.Write(s)
+
+%>
+}}
+Note that we added "+" operator as an extension operator for the class System.Text.StringBuilder.
+
+* Change Set 30470 - 10/17/2009. Version 0.5.2.32072. Built with DLR Changeset 32072
+# Fixed a bug so that the default properties are retrieved when concatenating two COM objects.
+# Added support for extension methods. This is crucial for ASP.NET MVC support since many HtmlHelper methods are extension methods.
+# Created ASP view engine for ASP.NET MVC.
+# Ported [NerdDinner sample](http://nerddinner.codeplex.com) to use the ASP view engine. See [Port NerdDinner Sample to ASP View Engine](Port-NerdDinner-Sample-to-ASP-View-Engine) for more details.
+* Change Set 29666 - 10/08/2009*  Initial release of version 0.5.1.31188. Built with DLR Changeset 31188.

docs/Installation.md

@@ -0,0 +1,20 @@
+# Installation
+
+## Build for .Net framework 2.0, 3.0, 3.5
+* Components that need to be copied to the bin dir of your web application
+|| Component Name || Description ||
+| Dlrsoft.asp.dll | ASP Classic Compiler runtime |
+| Dlrsoft.VBParser.dll | VBScript Parser |
+| Dlrsoft.VBScript.dll | VBScript.net compiler |
+| Microsoft.Dynamic.dll | Microsoft Dynamic Language Runtime |
+| Microsoft.Scripting.Core.dll | Microsoft Dynamic Language Runtime |
+| Microsoft.Scripting.dll | Microsoft Dynamic Language Runtime |
+| Microsoft.Scripting.ExtensionAttribute.dll | Microsoft Dynamic Language Runtime |
+* Configure the ASP Classic Compiler Http Handler. Add the following line to the httpHandlers section of web.config file:
+{{
+    <add verb="**" path="**.asp" validate="false" type="Dlrsoft.Asp.AspHandler, Dlrsoft.Asp"/>
+}}
+Note that if you want to use a different file extension for ASP Classic Compiler, just modify the path attribute.
+* (optional) Configure ISAPI extensions. This step is required only if you want to use ASP Classic Compiler to handle asp pages in IIS. It is not required in Cassini.
+	* IIS 5/6: In IIS Manager, go to Web Site Properties, on the Home Directory tab, click Configuration.... In Mappings tab, you will notice that asp is currently mapped to C:\WINDOWS\system32\inetsrv\asp.dll. Change it to executable that .aspx extension is using, e.g., c:\windows\microsoft.net\framework\v2.0.50727\aspnet_isapi.dll.
+Note that if you use a different file extension for ASP Classic Compiler, just create a new ISAPI extension mapping.

docs/Port NerdDinner Sample to ASP View Engine.md

@@ -0,0 +1,36 @@
+Starting with change set 30470, we added an ASP.NET MVC sample that uses ASP Classic Compiler as a view engine. This sample was ported from the [NerdDinner sample](http://nerddinner.codeplex.com). We replaced all the webform views in the Dinner directory with ASP views. This should make the migration from Classic ASP to ASP.NET MVC with ASP view to a full ASP.NET MVC application very easy.
+
+Most of the porting is quite trivial. I only need to mention a few things:
+# Since ASP view does not support master pages, we use Html.RenderPartial instead.
+# It is possible to mix the ASP view engine and the webform view engine. It is even possible to mix the view in a single page. This is demonstrated in the /Home/Index.asp view. We use ASP as the view but it uses the Login control as it's partial view.
+# C# supports the using block so that the object is disposed at the end of the block. The Dinner/Delete view uses HtmlHelper.BeginForm() in this way. We have to use slightly different syntax in delete.asp to dispose the object so that it will generate the {</form>} tag.
+# C# supports anonymous class and object initializer. VBScript does not have equivalent syntax. So our code in Dinner/RSVPStatus.asc is slightly longer. Note that we use the imports statement at the beginning to import the namespace so that we can instantiate the AjaxOptions object later. We want to come out with our own anonymous class.
+
+## Built-in objects in ASP page when used as ASP.NET MVC view
+
+The following are the built-in objects supported in the ASP view pages:
+* context - HttpContext
+* request - HttpRequest
+* session - Session wrapper
+* server - Server wrapper
+* application - Application wrapper
+* response - Response wrapper
+* writer - TextWriter. Same as the TextWrite in webform view.
+* viewcontext - ViewContext. Same as the webform view.
+* viewdata - ViewDataDictionary. Same as the webform view.
+* model - Model. Same as the webform view.
+* tempdata - TempDataDictionary. Same as the webform view.
+* ajax - AjaxHelper. Same as the webform view.
+* html - HtmlHelper. Same as the webform view.
+* url - UrlHelper. Same as the webform view.
+
+## Include ASP view engine.
+
+It is fairly simply to use the ASP view engine:
+# Add reference to the dlls described in [Installation](Installation) in your ASP.NET MVC project.
+# In global.asax.cs, add {"using Dlrsoft.Asp.Mvc"}.
+# In Application_Start procedure, add {"ViewEngines.Engines.Add(new WebFormViewEngine());"}
+
+The ASP view engine locate views in the views directory using the following patterms /Views/Controller/Action.asp and Views/Shared/Action.asp.
+
+When locating partial views, the ASP view engine uses two additional patterns: /Views/Controller/Action.asc and Views/Shared/Action.asc.