From e7f3fc61ce2765864f8c5a95734b8b105d333efc Mon Sep 17 00:00:00 2001 From: Deborah Kurata Date: Tue, 24 May 2016 11:39:07 -0700 Subject: [PATCH] docs(cb-vs2015) new cookbook for Visual Studio 2015 QuickStart closes #1502 --- .../cb-visual-studio-2015/ts/.gitignore | 1 + .../cb-visual-studio-2015/ts/tsconfig.json | 14 ++ public/docs/dart/latest/cookbook/_data.json | 6 + .../latest/cookbook/visual-studio-2015.jade | 1 + public/docs/js/latest/cookbook/_data.json | 5 + .../latest/cookbook/visual-studio-2015.jade | 1 + public/docs/ts/latest/cookbook/_data.json | 5 + .../latest/cookbook/visual-studio-2015.jade | 160 ++++++++++++++++++ 8 files changed, 193 insertions(+) create mode 100644 public/docs/_examples/cb-visual-studio-2015/ts/.gitignore create mode 100644 public/docs/_examples/cb-visual-studio-2015/ts/tsconfig.json create mode 100644 public/docs/dart/latest/cookbook/visual-studio-2015.jade create mode 100644 public/docs/js/latest/cookbook/visual-studio-2015.jade create mode 100644 public/docs/ts/latest/cookbook/visual-studio-2015.jade diff --git a/public/docs/_examples/cb-visual-studio-2015/ts/.gitignore b/public/docs/_examples/cb-visual-studio-2015/ts/.gitignore new file mode 100644 index 0000000000..ca3f2dbd5e --- /dev/null +++ b/public/docs/_examples/cb-visual-studio-2015/ts/.gitignore @@ -0,0 +1 @@ +!tsconfig.json diff --git a/public/docs/_examples/cb-visual-studio-2015/ts/tsconfig.json b/public/docs/_examples/cb-visual-studio-2015/ts/tsconfig.json new file mode 100644 index 0000000000..1ac74de56e --- /dev/null +++ b/public/docs/_examples/cb-visual-studio-2015/ts/tsconfig.json @@ -0,0 +1,14 @@ +{ + "compilerOptions": { + "target": "es5", + "module": "commonjs", + "moduleResolution": "node", + "sourceMap": true, + "emitDecoratorMetadata": true, + "experimentalDecorators": true, + "removeComments": false, + "noImplicitAny": true, + "suppressImplicitAnyIndexErrors": true + }, + "compileOnSave": true +} diff --git a/public/docs/dart/latest/cookbook/_data.json b/public/docs/dart/latest/cookbook/_data.json index 9b2545ec5e..207dce5e42 100644 --- a/public/docs/dart/latest/cookbook/_data.json +++ b/public/docs/dart/latest/cookbook/_data.json @@ -44,5 +44,11 @@ "title": "TypeScript to JavaScript", "intro": "Convert Angular 2 TypeScript examples into ES5 JavaScript", "hide": true + }, + + "visual-studio-2015": { + "title": "Visual Studio 2015 QuickStart", + "intro": "Use Visual Studio 2015 with the QuickStart files", + "hide": true } } diff --git a/public/docs/dart/latest/cookbook/visual-studio-2015.jade b/public/docs/dart/latest/cookbook/visual-studio-2015.jade new file mode 100644 index 0000000000..f8df2a84a6 --- /dev/null +++ b/public/docs/dart/latest/cookbook/visual-studio-2015.jade @@ -0,0 +1 @@ +!= partial("../../../_includes/_ts-temp") \ No newline at end of file diff --git a/public/docs/js/latest/cookbook/_data.json b/public/docs/js/latest/cookbook/_data.json index 2d9ada59f1..7b847da507 100644 --- a/public/docs/js/latest/cookbook/_data.json +++ b/public/docs/js/latest/cookbook/_data.json @@ -39,6 +39,11 @@ "ts-to-js": { "title": "TypeScript to JavaScript", "intro": "Convert Angular 2 TypeScript examples into ES5 JavaScript" + }, + + "visual-studio-2015": { + "title": "Visual Studio 2015 QuickStart", + "intro": "Use Visual Studio 2015 with the QuickStart files" } } diff --git a/public/docs/js/latest/cookbook/visual-studio-2015.jade b/public/docs/js/latest/cookbook/visual-studio-2015.jade new file mode 100644 index 0000000000..f8df2a84a6 --- /dev/null +++ b/public/docs/js/latest/cookbook/visual-studio-2015.jade @@ -0,0 +1 @@ +!= partial("../../../_includes/_ts-temp") \ No newline at end of file diff --git a/public/docs/ts/latest/cookbook/_data.json b/public/docs/ts/latest/cookbook/_data.json index a90160de7b..7043e62696 100644 --- a/public/docs/ts/latest/cookbook/_data.json +++ b/public/docs/ts/latest/cookbook/_data.json @@ -39,5 +39,10 @@ "ts-to-js": { "title": "TypeScript to JavaScript", "intro": "Convert Angular 2 TypeScript examples into ES5 JavaScript" + }, + + "visual-studio-2015": { + "title": "Visual Studio 2015 QuickStart", + "intro": "Use Visual Studio 2015 with the QuickStart files" } } diff --git a/public/docs/ts/latest/cookbook/visual-studio-2015.jade b/public/docs/ts/latest/cookbook/visual-studio-2015.jade new file mode 100644 index 0000000000..db6562670c --- /dev/null +++ b/public/docs/ts/latest/cookbook/visual-studio-2015.jade @@ -0,0 +1,160 @@ +include ../_util-fns + + +:marked + Some developers prefer Visual Studio as their Interactive Development Environment (IDE). + + This cookbook describes the steps required to set up and use the + Angular 2 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: + +:marked + - [Prerequisite](#prereq): Install Node.js + - [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 + +.l-main-section +h2#prereq 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`** + 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 +:marked + [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#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 + +:marked + Create the ASP.NET 4.x project as follows: + + * In Visual Studio, select `File` | `New` | `Project` from the menu. + * In the template tree, select `Templates` | `Visual C#` (or `Visual Basic`) | `Web`. + * Select the `ASP.NET Web Application` template, give the project a name, and click OK. + * Select the desired ASP.NET 4.5.2 template and click OK. + +.l-sub-section + :marked + In this cookbook we'll select the `Empty` template with no added folders, + 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 + +:marked + Copy the QuickStart files we downloaded from github into the folder containing the `.csproj` file. + Include the files in the Visual Studio project as follows: + + * Click the `Show All Files` button in Solution Explorer to reveal all of the hidden files in the project. + * Right-click on each folder/file to be included in the project and select `Include in Project`. + Minimally, include the following folder/files: + * app folder (answer *No* if asked to search for TypeScript Typings) + * styles.css + * index.html + * package.json + * tsconfig.json + * typings.json + +.l-main-section +h2#restore Step 5: Restore the required packages +:marked + Restore the packages required for an Angular application as follows: + + * Right-click on the `package.json` file in Solution Explorer and select `Restore Packages`. +
This uses `npm` to install all of the packages defined in the `package.json` file. + It may take some time. + * If desired, open the Output window (`View` | `Output`) to watch the npm commands execute. + * Ignore the warnings. + * 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 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 + +:marked + Click the Run button or press F5 to build and run the application. + + This launches the default browser and runs 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. +