Documentation update for Spring 2017 Creators Update for Visual Studi…

…o 2017 v15.3

Changelog.md

@@ -60,7 +60,7 @@ As we’ve improved the quality and maturity of the projection, we’ve also red
 
 While the C++/WinRT language projection is designed to provide no-compromise access to the modern Windows API, we recognize that there are instances where you need to interop with other libraries or tools that may not support C++/WinRT directly. The base library (winrt/base.h) provides a set of helper functions that assist in converting between C++/WinRT types and their equivalents in other language projections such as C++/CX or the Windows SDK headers produced by the MIDL compiler. Although we don’t directly support interop with other language projections, to avoid cross-dependencies, you can use the following helper functions to streamline the process as you migrate your code to C++/WinRT.
 
-See the [Interoperability Helper Functions] (./Docs/Interoperability Helper Functions.md) document for all the details and examples.
+See the [Interoperability Helper Functions](./Docs/Interoperability%20Helper%20Functions.md) document for all the details and examples.
 
 
 #### Simplified and more intuitive parameter binding for strings and collections
@@ -90,7 +90,7 @@ You may notice that objects created with winrt::implements now provide a default
 C++/WinRT provides the fastest factory caching of any language projection. However, due to the unfortunate relationship between COM statics, the CRT, and the OS loader it is entirely possible that those statics are not torn down correctly when C++/WinRT is used within a DLL. We now provide an option to disable caching in those cases. We are also investigating how we might finally solve the problem of COM statics once and for all.
 
 #### Experimental natvis support
-The experimental natvis support makes it easier to interrogate C++/WinRT types from within a debugger.
+The experimental natvis support makes it easier to interrogate C++/WinRT types from within a debugger.  See [Debug Visualization - Experimental](./Docs/Debug%20Visualization%20-%20Experimental.md) for details on how to use this support.
 
 ### Summary
 Those are just a few highlights for now. We have worked hard to build a world-class language projection for the systems programmer and the app developer alike. Our goal is to enable C++ developers to write beautiful high-performance apps and components with incredible ease.

Docs/Debug Visualization - Experimental.md

@@ -0,0 +1,44 @@
+This release of C++/WinRT contains experimental support for Visual Studio native debug visualization (natvis), via the cppwinrt.natvis script.
+
+## Installing
+
+You can manually install cppwinrt.natvis by simply copying it to your per-machine or per-user Visualizers folder.
+
+### Per-Machine
+    %VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers\
+
+### Per-User
+(you may have to create this folder first)
+
+    %USERPROFILE%\My Documents\Visual Studio 2017\Visualizers
+
+To make it easier to update, you might consider creating a symbolic link from a Visualizers folder to your cppwinrt repo:
+
+    mklink "%USERPROFILE%\My Documents\Visual Studio 2017\Visualizers\cppwinrt.natvis" c:\cppwinrt\10.0.15063.0\winrt\cppwinrt.natvis 
+
+## Visualizing
+
+To see the debug visualization support in action:
+* Open the Syndication sample (\cppwinrt\10.0.15063.0\Samples\Syndication)
+* Set a breakpoint after the construction of the uri variable
+* Build and debug
+* When the breakpoint hits, add the uri variable to the watch window, expand it, and refresh its top node.  The uri's property values should be displayed in the debugger.  
+* You can also simply mouse over the uri variable, and click the refresh button in the tooltip to see the default visualization value, supplied via the uri's IStringable::ToString() method.
+
+![](../media/natvis.png)
+
+## Limitations
+Note that this support is experimental and currently has some limitations.  For example, visualization is not supported for nested objects.  In addition, visualization requires a debugger call back into your application code to retrieve property values (the reason for the explicit refresh).  This is accomplished with a small stub, ```WINRT_get_val```, defined by the C++/WinRT library.  Inclusion of this stub is automatic for debug builds.  It can be opted into for release builds, by defining the symbol ```WINRT_NATVIS```.  We hope to remove these limitations in a future release.
+
+## Troubleshooting
+If you have no success visualizing your C++/WinRT variable, you can try troubleshooting by enabling verbose natvis output via: 
+
+    Tools / Options / Debugging / Output Window / Natvis diagnostic messages (C++ only)
+
+When you restart the debugging session, the Debug Output pane should display entries like this:
+
+    Natvis: Parsing natvis xml file: C:\...\cppwinrt.natvis.
+    Natvis: C:\...\cppwinrt.natvis(6890,21): Successfully parsed expression 'WINRT_get_val(this,L"{96369F54-8EB6-48F0-ABCE-C1B211E627C3}",0).s' in type context 'winrt::Windows::Foundation::Uri'.
+
+If errors are displayed, please log an issue.
+

Getting Started.md

@@ -115,14 +115,14 @@ If you are not working in Visual Studio, set the **MinVersion** and
 Read the docs!
 ==============
 
-To learn how to use the C++/WinRT library, browse the [Docs] (./Docs) folder for topics of interest.
+To learn how to use the C++/WinRT library, browse the [Docs](./Docs) folder for topics of interest.
 
-The [Header File Design] (./Docs/Header File Design.md) document contains a great discussion of the architecture of and best practices for using the C++/WinRT header files.
+The [Header File Design](./Docs/Header%20File%20Design.md) document contains a great discussion of the architecture of and best practices for using the C++/WinRT header files.
 
-For a discussion of the naming conventions used in the C++/WinRT library, read [Naming Conventions] (./Docs/Naming Conventions.md).
+For a discussion of the naming conventions used in the C++/WinRT library, read [Naming Conventions](./Docs/Naming Conventions.md).
 
-Unlike C++/CX, with C++/WinRT you typically pass and receive familar C++ data types when calling WinRT APIs. More information is in [Using Standard C++ types with C++ WinRT] (./Docs/Using Standard C++ types with C++ WinRT.md).
+Unlike C++/CX, with C++/WinRT you typically pass and receive familar C++ data types when calling WinRT APIs. More information is in [Using Standard C++ types with C++ WinRT](./Docs/Using%20Standard%20C++%20types%20with%20C++%20WinRT.md).
 
-For information about how to migrate existing C++/CX code to C++/WinRT, read [Migrating C++ CX source code to C++ WinRT] (./Docs/Migrating C++ CX source code to C++ WinRT.md).
+For information about how to migrate existing C++/CX code to C++/WinRT, read [Migrating C++ CX source code to C++ WinRT](./Docs/Migrating%20C++%20CX%20source%20code%20to%20C++%20WinRT.md).
 
-When you need to write code that works directly with COM and WinRT interfaces, you'll find the necessary information in [Interoperability Helper Functions] (./Docs/Interoperability Helper Functions.md).
+When you need to write code that works directly with COM and WinRT interfaces, you'll find the necessary information in [Interoperability Helper Functions](./Docs/Interoperability%20Helper%20Functions.md).

README.md

@@ -50,9 +50,9 @@ pull requests. Please read this entire page carefully.
 
 #### From an engineering standpoint, please make sure that you can build and test the code. Familiarize yourself with our project guidelines and coding conventions. 
 We recommend that you read these great posts about open source: 
-* [Open Source Contribution Etiquette] (http://tirania.org/blog/archive/2010/Dec-31.html) by Miguel de Icaza 
-* [Don't "Push" Your Pull Requests] (https://www.igvita.com/2011/12/19/dont-push-your-pull-requests) by Ilya Grigorik 
-* [A Successful Git Branching Model] (http://nvie.com/posts/a-successful-git-branching-model/) by Vincent Driessen 
+* [Open Source Contribution Etiquette](http://tirania.org/blog/archive/2010/Dec-31.html) by Miguel de Icaza 
+* [Don't "Push" Your Pull Requests](https://www.igvita.com/2011/12/19/dont-push-your-pull-requests) by Ilya Grigorik 
+* [A Successful Git Branching Model](http://nvie.com/posts/a-successful-git-branching-model/) by Vincent Driessen 
 
 Before you start working on a feature or substantial code contribution please discuss it with the team and ensure it is an appropriate addition to the core product. 
 
@@ -139,4 +139,4 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
 
 Copyright (c) Microsoft Corporation. All rights reserved.
 
-Licensed under the [MIT] (LICENSE) License.
+Licensed under the [MIT](LICENSE) License.