Merge pull request #1698 from MicrosoftDocs/master

3/28 AM Publish

Author: Taojunshen

docs/ide/adding-references-using-nuget-versus-an-extension-sdk.md

@@ -15,40 +15,40 @@ manager: ghogen
 ms.workload: 
   - "multiple"
 ---
-# Adding References Using NuGet Versus an Extension SDK
+# Adding references using NuGet versus an extension SDK
 
 You can provide a package for consumption within Visual Studio projects by using either the NuGet extension to Visual Studio or a software development kit (SDK). By describing the similarities and differences between the two mechanisms, this topic can help you choose the best one for your task.
 
 - NuGet is an open-source, package-management system that simplifies the process of incorporating libraries into a project solution. For more information, see the [NuGet documentation](/nuget).
 
 - An SDK is a collection of files that Visual Studio treats as a single reference item. The **Reference Manager** dialog box lists all SDKs that are relevant to the project that's open when you display that dialog box. When you add an SDK to a project, you can access all of the contents of that SDK through IntelliSense, the **Toolbox**, designers, the **Object Browser**, MSBuild, deployment, debugging, and packaging. For more information about SDKs, see [Creating a Software Development Kit](../extensibility/creating-a-software-development-kit.md).
 
-## Which Mechanism Should I Use?
+## Which mechanism should I use?
 
 The following table helps you compare the referencing features of an SDK with the referencing features of NuGet.
 
 |Feature|SDK Support|SDK Notes|NuGet Support|NuGet Notes|
 |-------------|-----------------|---------------|-------------------|-----------------|
 |The mechanism references one entity and then all the files and functionality are available.|Y|You add an SDK by using the **Reference Manager** dialog box, and all the files and functionality are available during the development workflow.|Y||
-|MSBuild automatically consumes assemblies and Windows metadata (.winmd) files.|Y|References in the SDK are automatically passed to the compiler.|Y||
-|MSBuild automatically consumes the  .h or .lib files.|Y|The *SDKName*.props file tells Visual Studio how to set up the Visual C++ directory, and so forth, for automatic .h or .lib file consumption.|N||
-|MSBuild automatically consumes the  .js or .css files.|Y|In **Solution Explorer**, you can expand the JavaScript SDK reference node to show individual .js or .css files and then generate `<source include/>` tags by dragging those files to their source files. The SDK supports F5 and automatic package setup.|Y||
+|MSBuild automatically consumes assemblies and Windows metadata (*.winmd*) files.|Y|References in the SDK are automatically passed to the compiler.|Y||
+|MSBuild automatically consumes the  .h or .lib files.|Y|The *SDKName.props* file tells Visual Studio how to set up the Visual C++ directory, and so forth, for automatic *.h* or *.lib* file consumption.|N||
+|MSBuild automatically consumes the  *.js* or *.css* files.|Y|In **Solution Explorer**, you can expand the JavaScript SDK reference node to show individual *.js* or *.css* files and then generate `<source include/>` tags by dragging those files to their source files. The SDK supports F5 and automatic package setup.|Y||
 |MSBuild automatically adds the control in the **Toolbox**.|Y|The **Toolbox** can consume SDKs and show controls in the tabs that you specify.|N||
 |The mechanism supports Visual Studio Installer for extensions (VSIX).|Y|VSIX has a special manifest and logic to create SDK packages|Y|The VSIX can be embedded in another setup program.|
 |The **Object Browser** enumerates references.|Y|The **Object Browser** automatically gets the list of references in SDKs and enumerates them.|N||
 |Files and links automatically get added to  the **Reference Manager** dialog box (help links, and so forth auto populate)|Y|The **Reference Manager** dialog box automatically enumerates SDKs, along with help links and the list of SDK dependencies.|N|NuGet provides its own **Manage NuGet Packages** dialog box.|
 |The mechanism supports multiple architectures.|Y|SDKs can ship multiple configurations. MSBuild consumes the appropriate files for each project configuration.|N||
 |The mechanism supports multiple configurations.|Y|SDKs can ship multiple configurations. Depending on project architecture, MSBuild consumes the appropriate files for each project architecture.|N||
-|The mechanism can specify "not to copy."|Y|Depending on whether files are dropped in the \redist or \designtime folder, you can control which files to copy into the consuming application's package.|N|You declare which files to copy in the package manifest.|
+|The mechanism can specify "not to copy."|Y|Depending on whether files are dropped in the *\redist* or *\designtime* folder, you can control which files to copy into the consuming application's package.|N|You declare which files to copy in the package manifest.|
 |Content appears in localized files.|Y|Localized XML documents in SDKs are automatically included  for a better design-time experience.|N||
 |MSBuild supports consuming  multiple versions of an SDK simultaneously.|Y|The SDK supports consuming multiple versions simultaneously.|N|This isn't referencing. You can't have more than one version of NuGet files in your project at a time.|
 |The mechanism supports specifying applicable target frameworks, Visual Studio versions, and project types.|Y|The **Reference Manager** dialog box and the **Toolbox** show only the SDKs that apply to a project, so that users can more easily choose the appropriate SDKs.|Y (partial)|Pivot is the Target Framework. There is no filtering on user interface. At installation time, it might return an error.|
-|The mechanism supports specifying registration info for native WinMDs.|Y|You can specify the correlation between the .winmd file and the .dll file in SDKManifest.xml.|N||
+|The mechanism supports specifying registration info for native WinMDs.|Y|You can specify the correlation between the .winmd file and the .dll file in *SDKManifest.xml*.|N||
 |The mechanism supports specifying dependencies on other SDKs.|Y|The SDK only notifies the user; the user must still install them and reference them manually.|Y|NuGet pulls them automatically; the user isn't notified.|
 |The mechanism integrates with  [!INCLUDE[win8_appstore_long](../debugger/includes/win8_appstore_long_md.md)] concepts such as app manifest and Framework ID.|Y|The SDK must pass concepts that are specific to the [!INCLUDE[win8_appstore_short](../ide/includes/win8_appstore_short_md.md)] so that packaging and F5 work correctly with SDKs that are available in the[!INCLUDE[win8_appstore_short](../ide/includes/win8_appstore_short_md.md)].|N||
 |The mechanism  integrates with the app debugging pipeline for [!INCLUDE[win8_appname_long](../debugger/includes/win8_appname_long_md.md)] apps.|Y|The SDK must pass [!INCLUDE[win8_appstore_short](../ide/includes/win8_appstore_short_md.md)]-specific concepts so that packaging and F5 work correctly with SDKs available in the [!INCLUDE[win8_appstore_short](../ide/includes/win8_appstore_short_md.md)].|Y|NuGet content becomes part of the project. No special F5 consideration is needed.|
 |The mechanism integrates with app manifests.|Y|The SDK must pass [!INCLUDE[win8_appstore_short](../ide/includes/win8_appstore_short_md.md)]-specific concepts so that packaging and F5 work correctly with SDKs available in the [!INCLUDE[win8_appstore_short](../ide/includes/win8_appstore_short_md.md)].|Y|NuGet content becomes part of the project. No special F5 consideration is needed.|
-|The mechanism deploys non-reference files (for example, deploy test framework upon which to run tests of [!INCLUDE[win8_appname_long](../debugger/includes/win8_appname_long_md.md)] apps).|Y|If you drop the files in the \redist folder, the files are automatically deployed.|Y||
+|The mechanism deploys non-reference files (for example, deploy test framework upon which to run tests of [!INCLUDE[win8_appname_long](../debugger/includes/win8_appname_long_md.md)] apps).|Y|If you drop the files in the *\redist* folder, the files are automatically deployed.|Y||
 |The mechanism automatically adds the platform SDKs in Visual Studio IDE.|Y|If you drop the [!INCLUDE[win8](../debugger/includes/win8_md.md)] SDK or the Windows Phone SDK in a specific location with a specific layout, the SDK is automatically integrated with all the Visual Studio features.|N||
 |The mechanism supports a clean developer machine. (That is, no installation is required, and simple retrieval from source code control will work.)|N|Because you reference an SDK, you must check in your solution and the SDK separately. You can check in the SDK from the two non-registry default locations from which MSBuild iterates SDKs (for details, see [Creating a Software Development Kit](../extensibility/creating-a-software-development-kit.md)). As an alternative, if a custom location consists of the SDKs, you can specify the following code in the project file:<br /><br /> `<PropertyGroup>    <SDKReferenceDirectoryRoot>C:\MySDKs</SDKReferenceDirectoryRoot>   </PropertyGroup>`<br /><br /> Then check the SDKs into that location.|Y|You can check out the solution, and Visual Studio immediately recognizes and acts on the files.|
 |You can join a large existing community of package authors.|N/A|The community is new.|Y||
@@ -57,12 +57,12 @@ The following table helps you compare the referencing features of an SDK with th
 |The mechanism integrates with continuous-integration build servers for both package creation and consumption.|Y|The SDK must pass the checked-in location (SDKReferenceDirectoryRoot property) on command line to MSBuild.|Y||
 |The mechanism supports both stable and pre-release package versions.|Y|The SDK supports adding references to multiple versions.|Y||
 |The mechanism supports auto-update for installed packages.|Y|If shipped as VSIX or part of Visual Studio automatic updates, SDK provides automatic notifications.|Y||
-|The mechanism contains a stand-alone .exe file for creating and consuming packages.|Y|The SDK contains MSBuild.exe.|Y||
-|Packages can be checked into version control.|Y|You can't check in anything outside the Documents node, which means that the Extension SDKs might not be checked in.The size of Extension SDK might be large.|Y||
+|The mechanism contains a stand-alone *.exe* file for creating and consuming packages.|Y|The SDK contains *MSBuild.exe*.|Y||
+|Packages can be checked into version control.|Y|You can't check in anything outside the Documents node, which means that the Extension SDKs might not be checked in. The size of Extension SDK might be large.|Y||
 |You can use a PowerShell interface to create and consume packages.|Y (consumption), N (creation)|No tooling for creating an SDK. Consumption is executing MSBuild on the command line.|Y||
-|You can use a Symbol package for debugging support.|Y|If you drop .pdb files in the SDK, the files get picked up automatically.|Y||
+|You can use a Symbol package for debugging support.|Y|If you drop *.pdb* files in the SDK, the files get picked up automatically.|Y||
 |The mechanism supports package manager auto-updates.|N/A|The SDK gets revised with MSBuild.|Y||
-|The mechanism supports a lightweight manifest format.|Y|SDKManifest.xml supports many attributes, but a small subset is usually necessary.|Y||
+|The mechanism supports a lightweight manifest format.|Y|*SDKManifest.xml* supports many attributes, but a small subset is usually necessary.|Y||
 |The mechanism is available for  all Visual Studio editions.|Y|The SDK supports all Visual Studio editions.|Y|NuGet supports all Visual Studio editions.|
 |The mechanism is available for  all project types.|N|The SDK supports [!INCLUDE[win8_appname_long](../debugger/includes/win8_appname_long_md.md)] apps starting in [!INCLUDE[vs_dev11_long](../data-tools/includes/vs_dev11_long_md.md)].|N|You can review a list of allowed projects.|
 

docs/ide/adding-visual-studio-editor-support-for-other-languages.md

@@ -61,28 +61,28 @@ Learn about how the Visual Studio editor supports reading and navigating through
 
 -   C#  
 
- All of these file types have  the features described earlier even if support for a given language hasn't yet  been installed. Installing specialized support for some languages may provide additional language support, such as IntelliSense or other advanced language features such as Light Bulbs.  
+All of these file types have  the features described earlier even if support for a given language hasn't yet  been installed. Installing specialized support for some languages may provide additional language support, such as IntelliSense or other advanced language features such as Light Bulbs.  
 
 ## Adding support for non-supported languages  
  Visual Studio 2015 Update 1 and later versions provide language support in the editor by using [TextMate Grammars](https://manual.macromates.com/en/language_grammars). If your favorite programming language currently isn't supported in the Visual Studio editor, first, search the web - a TextMate bundle for the language may already exist. If you can't find one, though, you can add support for it yourself in Visual Studio 2015 Update 1 or later by creating a TextMate bundle  model for language grammars and snippets.  
 
  Add any new TextMate Grammars for Visual Studio in the following folder:  
 
- %userprofile%\\.vs\Extensions  
+ *%userprofile%\\.vs\Extensions*  
 
  Under this base path, add the following folder(s) if they apply to your situation:  
 
 |Folder Name|Description|  
 |-----------------|-----------------|  
-|\\*\<language name>*|The language folder. Replace *\<language name>* with the name of the language. For example, **\Matlab**.|  
-|\Syntaxes|The grammar folder. Contains the grammar .json files for the language, such as **Matlab.json**.|  
-|\Snippets|The snippets folder. Contains snippets for the language.|  
+|\\*\<language name>*|The language folder. Replace *\<language name>* with the name of the language. For example, *\Matlab*.|  
+|*\Syntaxes*|The grammar folder. Contains the grammar *.json* files for the language, such as *Matlab.json*.|  
+|*\Snippets*|The snippets folder. Contains snippets for the language.|  
 
- In Windows, %userprofile% resolves to the path: c:\Users\\*\<user name>*. If the extensions folder does not exist on your system, you will need to create it. If the folder already exists, it will be hidden.  
+ In Windows, *%userprofile%* resolves to the path: *c:\Users\\*\<user name>*.* If the extensions folder does not exist on your system, you will need to create it. If the folder already exists, it will be hidden.  
 
  For details about how to create TextMate Grammars, see [TextMate - Introduction to Language Grammars: How to add source code syntax highlighting embedded in HTML](https://developmentality.wordpress.com/2011/02/08/textmate-introduction-to-language-grammars/) and [Notes on how to create a Language Grammar and Custom Theme for a Textmate Bundle](https://benparizek.com/notebook/notes-on-how-to-create-a-language-grammar-and-custom-theme-for-a-textmate-bundle).  
 
-## See Also  
- [Visual Studio 2013 Navigate To Improvements](https://blogs.msdn.microsoft.com/mvpawardprogram/2013/10/22/visual-studio-2013-navigate-to-improvements/)   
- [Walkthrough: Creating a Code Snippet](../ide/walkthrough-creating-a-code-snippet.md)   
- [Walkthrough: Displaying Statement Completion](../extensibility/walkthrough-displaying-statement-completion.md)
+## See also  
+ [Visual Studio 2013 Navigate To improvements](https://blogs.msdn.microsoft.com/mvpawardprogram/2013/10/22/visual-studio-2013-navigate-to-improvements/)   
+ [Walkthrough: Creating a code snippet](../ide/walkthrough-creating-a-code-snippet.md)   
+ [Walkthrough: Displaying statement completion](../extensibility/walkthrough-displaying-statement-completion.md)

docs/ide/best-practices-for-using-code-snippets.md

@@ -22,13 +22,13 @@ The code in a code snippet shows only the most basic way to do something. For mo
 
 ## Handling exceptions
 
-Typically, code snippet Try...Catch blocks catch and rethrow all exceptions. That may not be the right choice for your project. For each exception, there are several ways to respond. For examples, see [How to: Handle an Exception Using try/catch (C#)](/dotnet/csharp/programming-guide/exceptions/how-to-handle-an-exception-using-try-catch) and [Try...Catch...Finally Statement (Visual Basic)](/dotnet/visual-basic/language-reference/statements/try-catch-finally-statement).
+Typically, code snippet Try...Catch blocks catch and rethrow all exceptions. That may not be the right choice for your project. For each exception, there are several ways to respond. For examples, see [How to: Handle an exception using try/catch (C#)](/dotnet/csharp/programming-guide/exceptions/how-to-handle-an-exception-using-try-catch) and [Try...Catch...Finally statement (Visual Basic)](/dotnet/visual-basic/language-reference/statements/try-catch-finally-statement).
 
 ## File locations
 
 When you adapt file locations to your application, you should think about the following:
 
-- Finding an accessible location. Users may not have access to the Program Files folder of the computer, so storing files with the application files may not work.
+- Finding an accessible location. Users may not have access to the *Program Files* folder of the computer, so storing files with the application files may not work.
 
 - Finding a secure location. Storing files in the root folder (*C:\\*) is not secure. For application data, we recommend the *Application Data* folder. For individual user data, the application can create a file for each user in the *Documents* folder.
 
@@ -50,7 +50,7 @@ How secure a snippet is depends on where it is used in the source code and how i
 
 - Passing data to scripting technologies
 
-For more information, see [Securing Applications](../ide/securing-applications.md).
+For more information, see [Securing applications](../ide/securing-applications.md).
 
 ## Downloaded code snippets
 
@@ -68,6 +68,6 @@ IntelliSense code snippets installed by Visual Studio are not in themselves a se
 
 ## See also
 
-[Visual Basic IntelliSense Code Snippets](/dotnet/visual-basic/developing-apps/using-ide/intellisense-code-snippets)  
-[Securing Applications](../ide/securing-applications.md)  
-[Code Snippets](../ide/code-snippets.md)
+[Visual Basic IntelliSense code snippets](/dotnet/visual-basic/developing-apps/using-ide/intellisense-code-snippets)  
+[Securing applications](../ide/securing-applications.md)  
+[Code snippets](../ide/code-snippets.md)