docs(vs-cookbook, deployment): update for use in VS 2015 (#3433)

Author: kapunahelewong

public/docs/ts/latest/cookbook/visual-studio-2015.jade

@@ -8,35 +8,35 @@ include ../_util-fns
    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.
+    There is no *live example* for this cookbook because it describes Visual Studio, not 
+    the QuickStart application itself.
 
 .l-main-section
 <a id="asp-net-4"></a>
 :marked
   ## ASP.NET 4.x Project
 
-  This cookbook explains how to set up the QuickStart files with an **ASP.NET 4.x project** in
-  Visual Studio 2015.
+  To set up the QuickStart files with an **ASP.NET 4.x project** in
+  Visual Studio 2015, follow these steps:
+
+:marked
+  *  [Prerequisite](#prereq1): Install Node.js.
+  *  [Prerequisite](#prereq2): Install Visual Studio 2015 Update 3.
+  *  [Prerequisite](#prereq3): Configure external web tools.
+  *  [Prerequisite](#prereq4): Install TypeScript 2.2 for Visual Studio 2015.
+  *  [Step 1](#download): Download the QuickStart files.
+  *  [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-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 template for Visual Studio 2015</a>. 
     Note that the resulting code does not map to the docs. Adjust accordingly.   
-  
-:marked
-  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](#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#prereq1 Prerequisite: Node.js
 :marked
@@ -45,7 +45,7 @@ h2#prereq1 Prerequisite: Node.js
 .l-sub-section
   :marked
     **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.
+    by running `node -v` and `npm -v` in a terminal window.
     Older versions produce errors.
 
 .l-main-section
@@ -63,29 +63,30 @@ 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`
+    * 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.
+  Visual Studio now looks first for external tools in the current workspace and 
+  if it doesn't find them, it looks in the global path. If Visual Studio doesn't 
+  find them in either location, it will use its own versions of the tools.
 
 .l-main-section
-h2#prereq4 Prerequisite: Install TypeScript 2 for Visual Studio 2015
+h2#prereq4 Prerequisite: Install TypeScript 2.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, 
+  While Visual Studio Update 3 ships with TypeScript support out of the box, it currently doesn’t ship with TypeScript 2.2, 
   which you need to develop Angular applications.
 
-  To install TypeScript 2:
+  To install TypeScript 2.2:
+
+   * Download and install **[TypeScript 2.2 for Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48593)**
 
-   * 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]`.
+   * 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/)**
+  You can find out more about TypeScript 2.2 support in Visual studio **[here](https://blogs.msdn.microsoft.com/typescript/2017/02/22/announcing-typescript-2-2/)**.
 
   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.
@@ -94,7 +95,7 @@ h2#prereq4 Prerequisite: Install TypeScript 2 for Visual Studio 2015
 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.
+  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
@@ -109,25 +110,25 @@ h2#create-project Step 2: Create the Visual Studio ASP.NET project
 
 .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.
+    This cookbook uses 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 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.
+  Copy the QuickStart files you 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
+
+    * src/app folder (answer *No*  if asked to search for TypeScript Typings)
+    * src/styles.css
+    * src/index.html
     * package.json
-    * tsconfig.json
+    * src/tsconfig.json
 
 .l-main-section
 h2#restore Step 4: Restore the required packages
@@ -139,32 +140,94 @@ h2#restore Step 4: Restore the required packages
     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`.
+  * When the restore is finished, a message in the bottom message bar of Visual Studio 
+    should say: `Installing packages complete`. Be patient. This could take a while.
   * Click the `Refresh` icon in Solution Explorer.
   * **Do not** include the `node_modules` folder in the project. Let it be a hidden project folder.
 
 .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.
+  First, ensure that `src/index.html` is set as the start page.
   Right-click `index.html` in Solution Explorer and select option `Set As Start Page`.
+
+  ### To run in VS with F5
+
+  Most Visual Studio developers like to press the F5 key and see the IIS server come up. 
+  To use the IIS server with the QuickStart app, you must make the following three changes. 
+
+  1. In `index.html`, change base href from `<base href="/">` to `<base href="/src/">`.
+  2. Also in `index.html`, change  the scripts to use `/node_modules` with a slash 
+  instead of `node_modules` without the slash. 
+  3. In `src/systemjs.config.js`, near the top of the file, 
+  change the npm `path` to `/node_modules/` with a slash.
 
-  Build and launch the app with debugger by clicking the **Run** button or press `F5`.
+.alert.is-important
+  :marked
+    After these changes, `npm start` no longer works.
+    You must choose to configure _either_ for F5 with IIS _or_ for  `npm start` with the lite-server.
+
+:marked
+  ### For apps that use routing
+
+  If your app uses routing, you need to teach the server to always return 
+  `index.html` when the user asks for an HTML page
+  for reasons explained in the [Deployment](deployment.html#fallback) guide.
+
+  Everything seems fine while you move about _within_ the app. 
+  But you'll see the problem right away if you refresh the browser
+  or paste a link to an app page (called a "deep link") into the browser address bar.
+
+  You'll most likely get a *404 - Page Not Found* response from the serer
+  for any address other than `/` or `/index.html`.
+  
+  You have to configure the server to return `index.html` for requests to these "unknown" pages.
+  The `lite-server` development server does out-of-the-box.
+  If you've switched over to F5 and IIS, you have to configure IIS to do it.
+  This section walks through the steps to adapt the QuickStart application.
+
+  #### Configure IIS rewrite rules
+
+  Visual Studio ships with IIS Express, which has the rewrite module baked in. 
+  However, if you're using regular IIS you'll have to install the rewrite 
+  module.  
+
+  Tell Visual Studio how to handle requests for route app pages by adding these 
+  rewrite rules near the bottom of the `web.config`:
+
+code-example(format='.').
+  &lt;system.webServer&gt;
+    &lt;rewrite&gt;
+      &lt;rules&gt;
+        &lt;rule name="Angular Routes" stopProcessing="true"&gt;
+          &lt;match url=".*" /&gt;
+          &lt;conditions logicalGrouping="MatchAll"&gt;
+            &lt;add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" /&gt;
+            &lt;add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" /&gt;
+          &lt;/conditions&gt;
+          &lt;action type="Rewrite" url="/src/" /&gt;
+        &lt;/rule&gt;
+      &lt;/rules&gt;
+    &lt;/rewrite&gt;
+  &lt;/system.webServer&gt;
+
+.l-sub-section
+  :marked
+    The match url, `<match url=".*" />`, will rewrite every request. You'll have to adjust this if 
+    you want some requests to get through, such as web API requests. 
+    
+    The URL in `<action type="Rewrite" url="/src/"/>` should 
+    match the base href in `index.html`.
+
+:marked
+  Build and launch the app with debugger by clicking the **Run** button or by pressing `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
+  Try editing any of the project files. Save and refresh the browser to
   see the changes. 
-  
-.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") ... 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. 

public/docs/ts/latest/guide/deployment.jade

@@ -456,21 +456,21 @@ code-example(format=".").
 :marked
   * [IIS](https://www.iis.net/): add a rewrite rule to `web.config`, similar to the one shown
   [here](http://stackoverflow.com/a/26152011/2116927):
-code-example(format="." escape="html").
-  <system.webServer>
-    <rewrite>
-      <rules>
-        <rule name="Angular Routes" stopProcessing="true">
-          <match url=".*" />
-          <conditions logicalGrouping="MatchAll">
-            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
-            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
-          </conditions>
-          <action type="Rewrite" url="/" />
-        </rule>
-      </rules>
-    </rewrite>
-  </system.webServer>
+code-example(format='.').
+  &lt;system.webServer&gt;
+    &lt;rewrite&gt;
+      &lt;rules&gt;
+        &lt;rule name="Angular Routes" stopProcessing="true"&gt;
+          &lt;match url=".*" /&gt;
+          &lt;conditions logicalGrouping="MatchAll"&gt;
+            &lt;add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" /&gt;
+            &lt;add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" /&gt;
+          &lt;/conditions&gt;
+          &lt;action type="Rewrite" url="/src/" /&gt;
+        &lt;/rule&gt;
+      &lt;/rules&gt;
+    &lt;/rewrite&gt;
+  &lt;/system.webServer&gt;
 
 :marked
   * [GitHub Pages](https://pages.github.com/): you can't

public/docs/ts/latest/guide/testing.jade

@@ -1682,7 +1682,7 @@ figure.image-display
   `By.css('*:not([highlight])')` finds _any_ element that does not have the directive.
 
 // Removed on 12/02/2016 when ceased public discussion of the `Renderer`. Revive in future?
-
+:marked
   * `DebugElement.styles` affords access to element styles even in the absence of a real browser, thanks to the `DebugElement` abstraction.
   But feel free to exploit the `nativeElement` when that seems easier or more clear than the abstraction.
 
@@ -1692,7 +1692,7 @@ figure.image-display
   and its `defaultColor`.
 
 // Removed on 12/02/2016 when ceased public discussion of the `Renderer`. Revive in future?
-
+:marked
   * `DebugElement.properties` affords access to the artificial custom property that is set by the directive.
 
 a(href="#top").to-top Back to top