From 7d142c1d788cb3493e65a93193d8114c9f4fa84a Mon Sep 17 00:00:00 2001 From: Deborah Kurata Date: Wed, 26 Oct 2016 09:26:40 -0700 Subject: [PATCH] docs(vs2015): update for current tools. (#2672) closes #2672 --- .../latest/cookbook/visual-studio-2015.jade | 161 +++++++++--------- 1 file changed, 84 insertions(+), 77 deletions(-) diff --git a/public/docs/ts/latest/cookbook/visual-studio-2015.jade b/public/docs/ts/latest/cookbook/visual-studio-2015.jade index ab996f617a..0359c626a6 100644 --- a/public/docs/ts/latest/cookbook/visual-studio-2015.jade +++ b/public/docs/ts/latest/cookbook/visual-studio-2015.jade @@ -5,40 +5,90 @@ 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 :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_ + ASP.NET Core + Angular 2 template for Visual Studio 2015. + 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#prereq2 Prerequisite: Visual Studio 2015 Update 3 +:marked + 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#prereq3 Prerequisite: Configure External Web tools +:marked + Configure Visual Studio to use the global external web tools instead of the tools that ship with Visual Studio: + + * 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#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 typescript@2.0`. + + 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 @@ -46,22 +96,10 @@ h2#download Step 1: Download the QuickStart files from github. If you downloaded as a zip file, extract the files. .l-main-section -h2#setup-vs Step 2: Set up Visual Studio for TypeScript -: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: - - * 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. - -.l-main-section -h2#create-project Step 3: Create the Visual Studio ASP.NET project +h2#create-project Step 2: Create the Visual Studio ASP.NET project :marked - Create the ASP.NET 4.x project as follows: + 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`. @@ -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. @@ -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: @@ -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 + +.l-main-section +h2#build-and-run Step 5: Build and run the app + +:marked + 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`. + + Build and launch the app with debugger by clicking the **Run** button or press `F5`. +.l-sub-section :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 + It's faster to run without the debugger by pressing `Ctrl-F5`. :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 - -: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. - - This launches the default browser and runs the QuickStart sample application. + 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`*" 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.