Merge pull request #3878 from MicrosoftDocs/master637034059079927327

For protected CLA branch, push strategy should use PR and merge to target branch method to work around git push error

Author: gewarren

docs/code-quality/ca1002-do-not-expose-generic-lists.md

@@ -25,24 +25,33 @@ ms.workload:
 |Breaking Change|Breaking|
 
 ## Cause
-A type contains an externally visible member that is a <xref:System.Collections.Generic.List%601?displayProperty=fullName> type, returns a <xref:System.Collections.Generic.List%601?displayProperty=fullName> type, or whose signature includes a <xref:System.Collections.Generic.List%601?displayProperty=fullName> parameter.
+
+A type contains an externally visible member that is a <xref:System.Collections.Generic.List%601?displayProperty=fullName> type, returns a <xref:System.Collections.Generic.List%601> type, or whose signature includes a <xref:System.Collections.Generic.List%601> parameter.
 
 ## Rule description
- <xref:System.Collections.Generic.List%601?displayProperty=fullName> is a generic collection that is designed for performance and not inheritance. <xref:System.Collections.Generic.List%601?displayProperty=fullName> does not contain virtual members that make it easier to change the behavior of an inherited class. The following generic collections are designed for inheritance and should be exposed instead of <xref:System.Collections.Generic.List%601?displayProperty=fullName>.
+
+<xref:System.Collections.Generic.List%601?displayProperty=fullName> is a generic collection that's designed for performance and not inheritance. <xref:System.Collections.Generic.List%601> does not contain virtual members that make it easier to change the behavior of an inherited class. The following generic collections are designed for inheritance and should be exposed instead of <xref:System.Collections.Generic.List%601>.
 
 - <xref:System.Collections.ObjectModel.Collection%601?displayProperty=fullName>
 
 - <xref:System.Collections.ObjectModel.ReadOnlyCollection%601?displayProperty=fullName>
 
 - <xref:System.Collections.ObjectModel.KeyedCollection%602?displayProperty=fullName>
 
+- <xref:System.Collections.Generic.IList%601?displayProperty=fullName>
+
+- <xref:System.Collections.Generic.ICollection%601?displayProperty=fullName>
+
 ## How to fix violations
-To fix a violation of this rule, change the <xref:System.Collections.Generic.List%601?displayProperty=fullName> type to one of the generic collections that is designed for inheritance.
+
+To fix a violation of this rule, change the <xref:System.Collections.Generic.List%601?displayProperty=fullName> type to one of the generic collections that's designed for inheritance.
 
 ## When to suppress warnings
-Do not suppress a warning from this rule unless the assembly that raises this warning is not meant to be a reusable library. For example, it would be safe to suppress this warning in a performance tuned application where a performance benefit was gained from the use of generic lists.
+
+Do not suppress a warning from this rule unless the assembly that raises this warning is not meant to be a reusable library. For example, it would be safe to suppress this warning in a performance-tuned application where a performance benefit was gained from the use of generic lists.
 
 ## Related rules
+
 [CA1005: Avoid excessive parameters on generic types](../code-quality/ca1005-avoid-excessive-parameters-on-generic-types.md)
 
 [CA1010: Collections should implement generic interface](../code-quality/ca1010-collections-should-implement-generic-interface.md)
@@ -58,4 +67,5 @@ Do not suppress a warning from this rule unless the assembly that raises this wa
 [CA1007: Use generics where appropriate](../code-quality/ca1007-use-generics-where-appropriate.md)
 
 ## See also
-[Generics](/dotnet/csharp/programming-guide/generics/index)
+
+[Generics](/dotnet/csharp/programming-guide/generics/index)

docs/code-quality/ca1051-do-not-declare-visible-instance-fields.md

@@ -32,17 +32,24 @@ By default, this rule only looks at externally visible types, but this is [confi
 
 ## Rule description
 
-The primary use of a field should be as an implementation detail. Fields should be `private` or `internal` and should be exposed by using properties. It is as easy to access a property as it is to access a field, and the code in the accessors of a property can change as the features of the type expand without introducing breaking changes. Properties that just return the value of a private or internal field are optimized to perform on par with accessing a field; very little performance gain is associated with the use of externally visible fields over properties.
+The primary use of a field should be as an implementation detail. Fields should be `private` or `internal` and should be exposed by using properties. It's as easy to access a property as it is to access a field, and the code in the accessors of a property can change as the features of the type expand without introducing breaking changes.
 
-Externally visible refers to `public`, `protected`, and `protected internal` (`Public`, `Protected`, and `Protected Friend` in Visual Basic) accessibility levels.
+Properties that just return the value of a private or internal field are optimized to perform on par with accessing a field; the performance gain from using externally visible fields instead of properties is minimal. *Externally visible* refers to `public`, `protected`, and `protected internal` (`Public`, `Protected`, and `Protected Friend` in Visual Basic) accessibility levels.
+
+Additionally, public fields cannot be protected by [Link demands](/dotnet/framework/misc/link-demands). For more information, see [CA2112: Secured types should not expose fields](../code-quality/ca2112-secured-types-should-not-expose-fields.md). (Link demands are not applicable to .NET Core apps.)
 
 ## How to fix violations
 
 To fix a violation of this rule, make the field `private` or `internal` and expose it by using an externally visible property.
 
 ## When to suppress warnings
 
-Do not suppress a warning from this rule. Externally visible fields do not provide any benefits that are unavailable to properties. Additionally, public fields cannot be protected by [Link Demands](/dotnet/framework/misc/link-demands). See [CA2112: Secured types should not expose fields](../code-quality/ca2112-secured-types-should-not-expose-fields.md).
+Only suppress this warning if you're certain that consumers need direct access to the field. For most applications, exposed fields do not provide performance or maintainability benefits over properties.
+
+Consumers may need field access in the following situations:
+
+- in ASP.NET Web Forms content controls
+- when the target platform makes use of `ref` to modify fields, such as model-view-viewmodel (MVVM) frameworks for WPF and UWP
 
 ## Configurability
 
@@ -66,4 +73,4 @@ The following example shows a type (`BadPublicInstanceFields`) that violates thi
 
 ## See also
 
-- [Link Demands](/dotnet/framework/misc/link-demands)
+- [Link Demands](/dotnet/framework/misc/link-demands)

docs/code-quality/ca1801-review-unused-parameters.md

@@ -43,21 +43,23 @@ This rule does not examine the following kinds of methods:
 
 - Methods declared with the `extern` (`Declare` statement in Visual Basic) modifier.
 
+If you're using [FxCop analyzers](install-fxcop-analyzers.md), this rule does not flag parameters that are named with the [discard](/dotnet/csharp/discards) symbol, for example, `_`, `_1`, and `_2`. This reduces warning noise on parameters that are needed for signature requirements, for example, a method used as a delegate, a parameter with special attributes, or a parameter whose value is implicitly accessed at run time by a framework but is not referenced in code.
+
 ## Rule description
 
-Review parameters in non-virtual methods that are not used in the method body to make sure no correctness exists around failure to access them. Unused parameters incur maintenance and performance costs.
+Review parameters in non-virtual methods that are not used in the method body to make sure no incorrectness exists around failure to access them. Unused parameters incur maintenance and performance costs.
 
-Sometimes a violation of this rule can point to an implementation bug in the method. For example, the parameter should have been used in the method body. Suppress warnings of this rule if the parameter has to exist because of backward compatibility.
+Sometimes, a violation of this rule can point to an implementation bug in the method. For example, the parameter should have been used in the method body. Suppress warnings of this rule if the parameter must exist because of backward compatibility.
 
 ## How to fix violations
 
-To fix a violation of this rule, remove the unused parameter (a breaking change) or use the parameter in the method body (a non-breaking change).
+To fix a violation of this rule, remove the unused parameter (a breaking change), or use the parameter in the method body (a non-breaking change).
 
 ## When to suppress warnings
 
 It is safe to suppress a warning from this rule:
 
-- For previously shipped code for which the fix would be a breaking change.
+- In previously shipped code for which the fix would be a breaking change.
 
 - For the `this` parameter in a custom extension method for <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert?displayProperty=nameWithType>. The functions in the <xref:Microsoft.VisualStudio.TestTools.UnitTesting.Assert> class are static, so there's no need to access the `this` parameter in the method body.
 
@@ -73,4 +75,4 @@ The following example shows two methods. One method violates the rule and the ot
 
 [CA1812: Avoid uninstantiated internal classes](../code-quality/ca1812-avoid-uninstantiated-internal-classes.md)
 
-[CA1804: Remove unused locals](../code-quality/ca1804-remove-unused-locals.md)
+[CA1804: Remove unused locals](../code-quality/ca1804-remove-unused-locals.md)

docs/code-quality/ca1821-remove-empty-finalizers.md

@@ -24,18 +24,23 @@ ms.workload:
 |Breaking Change|Non-breaking|
 
 ## Cause
+
 A type implements a finalizer that is empty, calls only the base type finalizer, or calls only conditionally emitted methods.
 
 ## Rule description
-Whenever you can, avoid finalizers because of the additional performance overhead that is involved in tracking object lifetime. The garbage collector will run the finalizer before it collects the object. This means that two collections will be required to collect the object. An empty finalizer incurs this added overhead without any benefit.
+
+Whenever you can, avoid finalizers because of the additional performance overhead that's involved in tracking object lifetime. The garbage collector runs the finalizer before it collects the object. This means that at least two collections are required to collect the object. An empty finalizer incurs this added overhead without any benefit.
 
 ## How to fix violations
+
 Remove the empty finalizer. If a finalizer is required for debugging, enclose the whole finalizer in `#if DEBUG / #endif` directives.
 
 ## When to suppress warnings
-Do not suppress a message from this rule. Failure to suppress finalization decreases performance and provides no benefits.
+
+Do not suppress a message from this rule.
 
 ## Example
+
 The following example shows an empty finalizer that should be removed, a finalizer that should be enclosed in `#if DEBUG / #endif` directives, and a finalizer that uses the `#if DEBUG / #endif` directives correctly.
 
-[!code-csharp[FxCop.Performance.RemoveEmptyFinalizers#1](../code-quality/codesnippet/CSharp/ca1821-remove-empty-finalizers_1.cs)]
+[!code-csharp[FxCop.Performance.RemoveEmptyFinalizers#1](../code-quality/codesnippet/CSharp/ca1821-remove-empty-finalizers_1.cs)]

docs/code-quality/ca2213-disposable-fields-should-be-disposed.md

@@ -67,7 +67,28 @@ The following snippet shows a type `TypeB` that violates rule CA2213 by declarin
 
 [!code-csharp[FxCop.Usage.IDisposableFields#1](../code-quality/codesnippet/CSharp/ca2213-disposable-fields-should-be-disposed_2.cs)]
 
+To fix the violation, call `Dispose()` on the disposable field:
+
+```csharp
+protected virtual void Dispose(bool disposing)
+{
+   if (!disposed)
+   {
+      // Dispose of resources held by this instance.
+      aFieldOfADisposableType.Dispose();
+
+      disposed = true;
+
+      // Suppress finalization of this disposed instance.
+      if (disposing)
+      {
+          GC.SuppressFinalize(this);
+      }
+   }
+}
+```
+
 ## See also
 
 - <xref:System.IDisposable?displayProperty=fullName>
-- [Dispose Pattern](/dotnet/standard/design-guidelines/dispose-pattern)
+- [Dispose pattern](/dotnet/standard/design-guidelines/dispose-pattern)

docs/ide/code-snippets.md

@@ -25,7 +25,7 @@ Code snippets are small blocks of reusable code that can be inserted in a code f
 > [!NOTE]
 > This topic applies to Visual Studio on Windows. For Visual Studio for Mac, see [Code snippets (Visual Studio for Mac)](/visualstudio/mac/snippets).
 
-Code snippets are available for a multitude of languages, including C#, C++, Visual Basic, XML, and T-SQL, to name a few. To view all the available installed snippets for a language, open the **Code Snippets Manager** from the **Tools** menu in Visual Studio, and choose the language from the drop-down menu at the top.
+Code snippets are available for a multitude of languages, including C#, C++, Visual Basic, XML, and T-SQL, to name a few. To view all the available installed snippets for a language, open the **Code Snippets Manager** from the **Tools** menu (or, press **Ctrl**+**K**, **Ctrl**+**B**), and choose the language from the drop-down menu at the top.
 
 ![Code Snippets Manager dialog box](media/code-snippets-manager.png)
 
@@ -35,7 +35,7 @@ Code snippets can be accessed in the following general ways:
 
 - From the right-click or context menu in the code editor, choose **Snippet** > **Insert Snippet**
 
-- From the keyboard, press **Ctrl**+**K**+**X**
+- From the keyboard, press **Ctrl**+**K**,**Ctrl**+**X**
 
 ## Expansion snippets and surround-with snippets
 
@@ -98,4 +98,4 @@ If you change `newPropertyValue` to `m_property`, then every instance of `newPro
 - [C# code snippets](../ide/visual-csharp-code-snippets.md)
 - [Visual C++ code snippets](../ide/visual-cpp-code-snippets.md)
 - [Code snippets schema reference](../ide/code-snippets-schema-reference.md)
-- [Code snippets (Visual Studio for Mac)](/visualstudio/mac/snippets)
+- [Code snippets (Visual Studio for Mac)](/visualstudio/mac/snippets)

docs/ide/default-keyboard-shortcuts-in-visual-studio.md

@@ -335,9 +335,13 @@ These keyboard shortcuts are *global*, which means that you can use them when an
 |--------------| - |
 |TestExplorer.DebugAllTests|**Ctrl+R, Ctrl+A**|
 |TestExplorer.DebugAllTestsInContext|**Ctrl+R, Ctrl+T**|
+|TestExplorer.DebugLastRun|**Ctrl+R, D**|
 |TestExplorer.RepeatLastRun|**Ctrl+R, L**|
 |TestExplorer.RunAllTests|**Ctrl+R, A**|
 |TestExplorer.RunAllTestsInContext|**Ctrl+R, T**|
+|TestExplorer.ShowTestExplorer|**Ctrl+E, T**|
+|LiveUnitTesting.OpenTab|**Ctrl+E, L**|
+|Test.CodeCoverageResults|**Ctrl+E, C**|
 
 ### <a name="bkmk_tools"></a> Tools
 
@@ -395,6 +399,7 @@ These keyboard shortcuts are *global*, which means that you can use them when an
 |View.WebBrowser|**Ctrl+Alt+R**|
 |View.ZoomIn|**Ctrl+Shift+.**|
 |View.ZoomOut|**Ctrl+Shift+,**|
+|TestExplorer.ShowTestExplorer|**Ctrl+E, T**|
 
 ### <a name="bkmk_window"></a> Window
 

docs/ide/template-parameters.md

@@ -55,7 +55,7 @@ The following table lists the reserved template parameters that can be used by a
 |safeitemrootname|Same as `safeitemname`.|
 |safeprojectname|The name provided by the user when the project was created but with all unsafe characters and spaces removed.|
 |time|The current time in the format DD/MM/YYYY 00:00:00.|
-|SpecificSolutionName|The name of the solution. When "create solution directory" is checked, `SpecificSolutionName` has the solution name. When "create solution directory" is not checked, `SpecificSolutionName` is blank.|
+|specifiedSolutionName|The name of the solution. When "create solution directory" is checked, `specifiedSolutionName` has the solution name. When "create solution directory" is not checked, `specifiedSolutionName` is blank.|
 |userdomain|The current user domain.|
 |username|The current user name.|
 |webnamespace|The name of the current website. This parameter is used in the web form template to guarantee unique class names. If the website is at the root directory of the web server, this template parameter resolves to the root directory of the web server.|

docs/modeling/create-layer-diagrams-from-your-code.md

@@ -35,7 +35,7 @@ Before you create a dependency diagram, make sure your solution has a modeling p
 ### Add a new dependency diagram to a modeling project
 
 > [!NOTE]
-> Dependency diagrams are not supported for .NET Core projects in Visual Studio.
+> Dependency diagrams for .NET Core projects are supported starting in Visual Studio 2019 version 16.2.
 
 1. On the **Architecture** menu, choose **New Dependency Diagram**.
 

docs/modeling/layer-diagrams-guidelines.md

@@ -20,7 +20,7 @@ Describe your app's architecture at a high level by creating *dependency diagram
 To see which editions of Visual Studio support this feature, see [Edition support for architecture and modeling tools](../modeling/what-s-new-for-design-in-visual-studio.md#VersionSupport).
 
 > [!NOTE]
-> Dependency diagrams are not supported for .NET Core projects in Visual Studio.
+> Dependency diagrams for .NET Core projects are supported starting in Visual Studio 2019 version 16.2.
 
 ## What is a dependency diagram?
 

docs/modeling/layer-diagrams-reference.md

@@ -28,7 +28,7 @@ In Visual Studio, you can use a *dependency diagram* to visualize the high-level
 To see which editions of Visual Studio support this feature, see [Edition support for architecture and modeling tools](../modeling/what-s-new-for-design-in-visual-studio.md#VersionSupport).
 
 > [!NOTE]
-> Dependency diagrams are not supported for .NET Core projects in Visual Studio.
+> Dependency diagrams for .NET Core projects are supported starting in Visual Studio 2019 version 16.2.
 
 You can specify the intended or existing dependencies between layers. These dependencies, which are represented as arrows, indicate which layers can use or currently use the functionality represented by other layers. By organizing your system into layers that describe distinct roles and functions, a dependency diagram can help make it easier for you to understand, reuse, and maintain your code.