Skip to content
This repository was archived by the owner on Dec 4, 2017. It is now read-only.

docs(vs2015): update for current tools. #2672

Merged
merged 1 commit into from
Oct 26, 2016
Merged

docs(vs2015): update for current tools. #2672

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 80 additions & 73 deletions public/docs/ts/latest/cookbook/visual-studio-2015.jade
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,63 +5,101 @@ include ../_util-fns
Some developers prefer Visual Studio as their Integrated Development Environment (IDE).

This cookbook describes the steps required to set up and use the
Angular QuickStart files in Visual Studio 2015 within an ASP.NET 4.x project.

Angular QuickStart files in **Visual Studio 2015 within an ASP.NET 4.x project**.
.l-sub-section
:marked
There is no *live example* for this cookbook because it describes Visual Studio, not the application.

.l-main-section
<a id="asp-net-4"></a>
:marked
## ASP.NET 4.x Project

The steps for setting up the QuickStart files with an ASP.NET 4.x project in
Visual Studio 2015 are as follows:

This cookbook explains how to set up the QuickStart files with an **ASP.NET 4.x project** in
Visual Studio 2015.
.l-sub-section
:marked
If you prefer a `File | New Project` experience and are using **ASP.NET Core**,
then consider the _experimental_
<a href="http://blog.stevensanderson.com/2016/10/04/angular2-template-for-visual-studio/" target="_blank">ASP.NET Core + Angular 2 template for Visual Studio 2015</a>.
Note that the resulting code does not map to the docs. Adjust accordingly.

:marked
- [Prerequisite](#prereq): Install Node.js
The steps are as follows:

- [Prerequisite](#prereq1): Install Node.js
- [Prerequisite](#prereq2): Install Visual Studio 2015 Update 3
- [Prerequisite](#prereq3): Configure External Web tools
- [Prerequisite](#prereq4): Install TypeScript 2 for Visual Studio 2015
- [Step 1](#download): Download the QuickStart files
- [Step 2](#setup-vs): Set up Visual Studio for TypeScript
- [Step 3](#create-project): Create the Visual Studio ASP.NET project
- [Step 4](#copy): Copy the QuickStart files into the ASP.NET project folder
- [Step 5](#restore): Restore required packages
- [Step 6](#edit-config): Edit the TypeScript configuration file
- [Step 7](#build-and-run): Build and run the app
- [Step 2](#create-project): Create the Visual Studio ASP.NET project
- [Step 3](#copy): Copy the QuickStart files into the ASP.NET project folder
- [Step 4](#restore): Restore required packages
- [Step 5](#build-and-run): Build and run the app

.l-main-section
h2#prereq Prerequisite: Node.js
h2#prereq1 Prerequisite: Node.js
:marked
Install **[Node.js® and npm](https://nodejs.org/en/download/)**
if they are not already on your machine.
.l-sub-section
:marked
**Verify that you are running node version `4.4.x` - `5.x.x`, and npm `3.x.x`**
**Verify that you are running node version `4.6.x` or greater, and npm `3.x.x` or greater**
by running `node -v` and `npm -v` in a terminal/console window.
Older versions produce errors.

.l-main-section
h2#download Step 1: Download the QuickStart files
h2#prereq2 Prerequisite: Visual Studio 2015 Update 3
:marked
[Download the QuickStart source](https://github.com/angular/quickstart)
from github. If you downloaded as a zip file, extract the files.
The minimum requirement for developing Angular 2 applications with Visual Studio is Update 3.
Earlier versions do not follow the best practices for developing applications with TypeScript.
To view your version of Visual Studio 2015, go to `Help | About Visual Studio`.

If you don't have it, install **[Visual Studio 2015 Update 3](https://www.visualstudio.com/en-us/news/releasenotes/vs2015-update3-vs)**.
Or use `Tools | Extensions and Updates` to update to Update 3 directly from Visual Studio 2015.

.l-main-section
h2#setup-vs Step 2: Set up Visual Studio for TypeScript
h2#prereq3 Prerequisite: Configure External Web tools
:marked
Ensure you have the latest version of Visual Studio 2015 installed.
Then open Visual Studio and install the latest set of TypeScript tools as follows:
Configure Visual Studio to use the global external web tools instead of the tools that ship with Visual Studio:

* Open `Tools` | `Extensions and Updates`.
* Select `Online` in the tree on the left.
* Search for `TypeScript` using the search box in the upper right.
* Select the most current available TypeScript version.
* Download and install the package.
* Open the **Options** dialog with `Tools` | `Options`
* In the tree on the left, select `Projects and Solutions` | `External Web Tools`.
* On the right, move the `$(PATH)` entry above the `$(DevEnvDir`) entries. This tells Visual Studio to
use the external tools (such as npm) found in the global path before using its own version of the external tools.
* Click OK to close the dialog.
* Restart Visual Studio for this change to take effect.

Visual Studio will now look first for external tools in the current workspace and
if not found then look in the global path and if it is not found there, Visual Studio
will use its own versions of the tools.

.l-main-section
h2#create-project Step 3: Create the Visual Studio ASP.NET project
h2#prereq4 Prerequisite: Install TypeScript 2 for Visual Studio 2015
:marked
While Visual Studio Update 3 ships with TypeScript support out of the box, it currently doesn’t ship with TypeScript 2,
which you need to develop Angular 2 applications.

To install TypeScript 2:
* Download and install **[TypeScript 2.0 for Visual Studio 2015](http://download.microsoft.com/download/6/D/8/6D8381B0-03C1-4BD2-AE65-30FF0A4C62DA/TS2.0.3-TS-release20-nightly-20160921.1/TypeScript_Dev14Full.exe)**
* OR install it with npm: `npm install -g [email protected]`.

You can find out more about TypeScript 2 support in Visual studio **[here](https://blogs.msdn.microsoft.com/typescript/2016/09/22/announcing-typescript-2-0/)**

At this point, Visual Studio is ready. It’s a good idea to close Visual Studio and
restart it to make sure everything is clean.

.l-main-section
h2#download Step 1: Download the QuickStart files
:marked
Create the ASP.NET 4.x project as follows:
[Download the QuickStart source](https://github.com/angular/quickstart)
from github. If you downloaded as a zip file, extract the files.

.l-main-section
h2#create-project Step 2: Create the Visual Studio ASP.NET project

:marked
Create the ASP.NET 4.x project in the usual way as follows:

* In Visual Studio, select `File` | `New` | `Project` from the menu.
* In the template tree, select `Templates` | `Visual C#` (or `Visual Basic`) | `Web`.
Expand All @@ -74,7 +112,7 @@ h2#create-project Step 3: Create the Visual Studio ASP.NET project
no authentication and no hosting. Pick the template and options appropriate for your project.

.l-main-section
h2#copy Step 4: Copy the QuickStart files into the ASP.NET project folder
h2#copy Step 3: Copy the QuickStart files into the ASP.NET project folder

:marked
Copy the QuickStart files we downloaded from github into the folder containing the `.csproj` file.
Expand All @@ -90,7 +128,7 @@ h2#copy Step 4: Copy the QuickStart files into the ASP.NET project folder
* tsconfig.json

.l-main-section
h2#restore Step 5: Restore the required packages
h2#restore Step 4: Restore the required packages
:marked
Restore the packages required for an Angular application as follows:

Expand All @@ -102,60 +140,29 @@ h2#restore Step 5: Restore the required packages
* When the restore is finished, a message should say: `npm command completed with exit code 0`.
* Click the `Refresh` icon in Solution Explorer.
* **Do not** include the `node_modules` folder in the project. Let it be a hidden project folder.
.alert.is-important
:marked
An error such as "*@angular/compiler is not in the npm registry*" suggests that Visual Studio 2015
is using an older version of npm. Update to the latest installed version of npm:

* `Tools` | `Options` to open the Options dialog.
* In the tree on the left, select `Projects and Solutions` | `External Web Tools`.
* On the right, move the `$(PATH)` entry above the `$(DevEnvDir`) entries. This tells Visual Studio to
use the external tools (such as npm) found in your path before using its own version of the external tools.
* Click OK to close the dialog.
* Restart Visual Studio for this change to take effect.

.l-main-section
h2#edit-config Step 6: Edit the TypeScript configuration file
:marked
For Visual Studio 2015 we must add `"compileOnSave": true` to the TypeScript configuration (`tsconfig.json`) file
as shown here.

+makeJson('cb-visual-studio-2015/ts/tsconfig.json', null, 'tsconfig.json (scripts)')

:marked
After making this change, **exit** Visual Studio and reopen it to reload the project.

.l-main-section
h2#build-and-run Step 7: Build and run the app
h2#build-and-run Step 5: Build and run the app

:marked
To set index.html as start page, right-click `index.html` in Solution Explorer and select option `Set As Start Page`.

Click the Run button or press F5 to build and run the application.
First, ensure that `index.html` is set as the start page.
Right-click `index.html` in Solution Explorer and select option `Set As Start Page`.

This launches the default browser and runs the QuickStart sample application.
Build and launch the app with debugger by clicking the **Run** button or press `F5`.
.l-sub-section
:marked
It's faster to run without the debugger by pressing `Ctrl-F5`.
:marked
The default browser opens and displays the QuickStart sample application.

Try editing any of the project files. *Save* and refresh the browser to
see the changes.

.alert.is-important
:marked
Compiler errors such as "*Property `map` does not exist on type `Observable<Response>`*" and
"*Observable cannot be found*" indicate an old release of Visual Studio.
Exit Visual Studio and follow the [instructions here](https://github.com/Microsoft/TypeScript/issues/8518).

You'll be asked to replace the file
code-example.
c:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\CommonExtensions\Microsoft\TypeScript.typescriptServices.js

:marked
This operation requires admin privileges.

.l-main-section
h2#routing Note on Routing Applications
:marked
If this application used the Angular router, a browser refresh could return a *404 - Page Not Found*.
Look at the address bar. Does it contain a navigation url (a "deep link")?
We'll have to configure the server to return `index.html` for these requests.
Until we do, remove the navigation path and refresh again.
Look at the address bar. Does it contain a navigation url (a "deep link") ... any path other than `/` or `/index.html`?

You'll have to configure the server to return `index.html` for these requests.
Until you do, remove the navigation path and refresh again.