The actual steps for setting up and using the ASP.NET MVC source code are quite simple and literally only take a few minutes (after you know what your doing).
STEP 1 – Install Tools
STEP 2 – Ensure environment is setup
STEP 3 – Install Source code from GitHub
STEP 4 – Configure VS to use Source Code
What is more challenging is understanding the steps, particularly if you don’t share a common core of experience with the authors sharing the information, i.e., I was lost even though I have been a hardcore Microsoft crony for many years, sticking primarily with Microsoft technologies such as Team Foundation Server for source control. I trust a new developer will easily fall into the same category.
I get it now, after many weeks and rabbit holes, it is the intent of this article to shorten your learning curve by consolidating all of the “bits” into one location…
My focus will be from a Microsoft Visual Studio developers perspective. I strongly recommend reviewing the following videos - they put everything into perspective - this blog post will make some assumptions that you are familiar with some of the information presented in these videos:
- DotNetConf 2014 - although the names have changed (from “K”) the information still applies
- DotNetConf 2015 - invaluable information for understanding the command line tools and ASP.NET VNext
STEP 1 – install the tools, in my case I installed the latest beta release (Beta 7) from HERE. This installs all of the necessary tooling (such as DNXVM.EXE, DNX.EXE, etc.).
Note:
You’re going to find a lot of references to command line utilities. With ASP.NET VNext the command prompt is a first class citizen. Why? Because it provides the same cross platform experience (transparent to the developer) whether they are on a Mac, Windows, or Linux box. For Windows users, if you use SysInternals Process Explorer utility while in Visual Studio you’ll find that Visual Studio invokes the command line utilities for its processing. |
STEP 2 – Ensure your environment is setup to utilize the newly installed .NET version. In my case I had been using Beta 6 so I had to update my system to utilize the latest release. I used the following command (by hitting the <WindowKey>-R and typing in “CMD”):
DNVM upgrade
The .NET Version Manager will install the latest version of the released .NET version (beta7), set its alias to “default” (used by Visual Studio), and then update both the process path and user path with the beta7 .NET environment (more on this below).
In the image below I typed “DNVM” alone (first arrow) so that I could see the help screen and version. Note that since I had executed the “DNVM update-self” earlier that I have the latest version of DNVM (beta8).
I then performed the “DNVM upgrade” (second arrow) so that my environment would be pointing to the latest released version beta7, followed by the command “DNVM list” so that I can verify that beta7 was active, and my default alias was pointing to beta7.
It is important to know the difference between the process path and user path. The process path will only apply for commands issued while in this command window; once you close the window the subsequent commands will revert back to the original version which in this case is 1.0.0-beta7. In contrast, if the user path is set then that setting will persist even when the command window is closed.
Note:
DNVM install 1.0.0-beta6 -Persistant would set the NET version to beta6 and persist the settings. In this case both the process and user paths are set. Without the –Persistant switch only the process path would be set. You would want to use DNVM install and -Persistant switch to switch to a version that is not the latest. |
Below I created an ASP.NET Web Application using the Visual Studio 2015 ASP.NET 5 Preview Templates (the “Empty” template). I then right clicked on the Web project AspNetBeta7Poc and selected “Open folder in Project Explorer”.
| TIP: from the Windows Explorer command line I replaced the path with “cmd” (see red oval in image below) so that I could open a command prompt in the project folder, required because commands such as DNX will use the current project location. |
From within the command prompt window I typed (bottom pane of image below):
DNX --version
which shows (in the image below) that I am using the beta7 version of DNX.EXE to load a Web host. I then execute the following command to launch a Web host (ref “Application started” in image below).
DNX web
After reviewing the project’s hosting.ini file I can see my port is 5000 so I open a browser to http://localhost:5000 to verify my page is loading (shows “Hello World” - see below image), I then hit Ctrl-C to abort the Web host.
To demonstrate how I can change the version for the current command window, I then change the .NET environment to beta6 by executing DNVM install 1.0.0-beta6 from the prompt. To verify my environment setting I typed DNX –version again which now shows the DNX.EXE utility will now use beta6 for processing.
Since I didn’t persist the setting when I close the command window my .NET environment will remain at beta7.
STEP 3 – with our .NET environment setup to point to beta7 it is now time to get the source code!
GitHub is an open source code repository that houses the ASP.NET open source projects. If you’re an old school Team Foundation Server (TFS) developer it will seem a wee bit foreign so I’ll provide an introduction to basic usage – enough to get you up and running quickly with your source code. Where it supports command line tools and processing, I opted to use the Windows utility.
Download the Windows Desktop GitHub application from HERE and install it. When it is done you will have the following two icons:
Double click the “GitHub” icon to launch the tool, patience is required for the application to startup.
- Once the GitHub application opens, click the gear on the top right corner of the application
- Select options.
- I already had a GitHub account (http://www.GitHub.com) so I plugged in my login/password
- I then set the “Clone path” to “E:\GitHub” which is my development drive. Note: the GitShell will default to the folder set here which makes life simpler.
- Save your settings (you can close the app or keep it open – won’t matter for the following steps)
With the Windows application installed you can now navigate to the source code that you would like to use. For demonstration purposes I’m going to use the Hosting source code at https://github.com/aspnet/Hosting
- The first thing you’ll need to do is “Fork a Repo” (button on top right of page - reference image below). This provides you with your own personal version that you can make changes to without affecting the original project - read more.
For etiquette information please review THIS LINK before getting started
- Next “Clone” your fork by clicking the applicable button (reference arrow #2), it will require a wee bit of patience (I thought it wasn’t doing anything my first time) as it will need to load the GitHub application if it is not open. It will then prompt you for the folder to install it in, you can simply click [OK] and it will install it under your configured folder.
Note: after my very first installation using the Microsoft Edge browser, the clone button took me to the Windows application download page. Even after I installed the application the button kept taking me to the download page. I had to run IE, click the button, have it launch the application, and “clone” (install) my source before I could use Microsoft Edge. Both browsers now work consistently (I am on Windows 10).
STEP 4 - Configure Visual Studio to use Source Control
For this process to work you have to “Clone in Desktop” and not “Download ZIP”.
Open your global.json file from the “Solution items” folder and on the “projects” line add the location of the GitHub source code. Be sure to add the “src” folder to your location, e.g., “e:/GitHub/Hosting/Src”, once you hit save, you’ll find after a momentary delay that the hosting project, and its dependencies, will automatically be added to your solution - in this case it added the three AspNet.Hosting projects shown below:
So now your project builds successfully and you attempt to run your web application and see the following error:
HTTP Error 403.14 Forbidden
The Web server is configured to not list the contents of this directory.
If you were running “web” versus IISExpress then you would see the exception
Microsoft.Dnx.Host.Clr.pdb not loaded
This is a red flag that there was an exception while executing code; the easiest way to troubleshoot this is to ensure you are using IISExpress and then enable CLR exceptions. From the Visual Studio 2015 menu you can select the following:
Debug | Windows | Exception Settings and then check “Common Language Runtime Exceptions”
Now when you run IISExpress the actual error reveals its ugly head:
System.TypeLoadException occurred
Message: Exception thrown: 'System.TypeLoadException' in Microsoft.AspNet.Loader.IIS.dll
Additional information: Method 'Initialize' in type 'Microsoft.AspNet.Loader.IIS.RuntimeHttpApplication' from assembly 'Microsoft.AspNet.Loader.IIS, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null' does not have an implementation.
This red flag suggests a versioning error so in closer investigation of the projects I find that my Hosting projects are using beta8 versus beta7 (reference image below):
To fix this I’ll go into my GitShell and change into my GitHub Hosting folder (reference image below). As I do, it reveals that I am in [dev] on the command line (within brackets in a cyan color) - so I execute the following:
git tag
to list the available tags and then I execute:
git checkout 1.0.0.0-beta7
This effectively selects beta 7 source code, my prompt changes to [1.0.0.0-beta7] and I notice that in Visual Studio the Hosting projects automatically process a “Restore Packages”, when done they accurately reveal references to beta7 (versus beta8) - all of the project versions are now in sync.
Although the Hosting projects correctly restored to beta7 you may find that your actual project is complaining with a yellow yield shaped icon (reference image below). To fix this, right click on the References node and select “Restore Packages”. You should then be able to compile and run the application.
So I launch the application and am happy to see that I hit my breakpoint in my Startup.ConfigureServices method on line 16 below.
I step out of this line and into the Hosting code to learn how it is possible that I can convert
void ConfigureServices(…)
to
IServiceProvider ConfigureServices(…)
and magically it will happily return, and use, my implementation of the ServiceProvider, e.g., Unity. My primary objective for wanting to step into the source code was so that I could learn how it was working under the hood - particularly when it wasn’t ;)
see BUG REPORT
So lines 41 true 43 show how a void method can return a value - my assumption is that under the hood MethodInfo.Invoke() will return null if void. This is a pretty cool little trick - I can also see that if null is returned that exportServices.BuildServiceProvider() will return an IServiceProvider reference.
I should note that in some videos and blogs they indicate that you’ll have to add the source code path to the “sources” element in your global.json file. Where I have seen this successfully add the projects automagically to the folder - I haven’t had much success hitting breakpoints (the source was being ignored). I did see in a video that someone added the path to the existing “projects” section so I tried this and and it has worked 100% of time.
Final note off topic: I dive a wee bit deeper into returning an IServiceProvider implementation in the following blog:
http://www.global-webnet.com/blog/post/2015/08/24/Dependency-Injection-in-ASPNET-vNext-(adding-Unity-container).aspx