Merge pull request #5633 from MicrosoftDocs/master637314671443344459

For protected CLA branch, push strategy should use PR and merge to target branch method to work around git push error
MicrosoftDocs · Jul 27, 2020 · 28243cc · 28243cc
2 parents ac140ed + ebaaff1
commit 28243cc
Show file tree

Hide file tree

Showing 7 changed files with 70 additions and 6 deletions.
diff --git a/docs/code-quality/ca1417.md b/docs/code-quality/ca1417.md
@@ -0,0 +1,59 @@
+---
+title: "CA1417: Do not use OutAttribute on string parameters for P/Invokes"
+ms.date: 07/20/2020
+ms.topic: reference
+f1_keywords:
+  - "DoNotUseOutAttributeStringPInvokeParameters"
+  - "CA1417"
+helpviewer_keywords:
+  - "DoNotUseOutAttributeStringPInvokeParameters"
+  - "CA1417"
+author: elinor-fung
+ms.author: elfung
+manager: jeffschw
+ms.workload:
+  - "multiple"
+---
+# CA1417: Do not use `OutAttribute` on string parameters for P/Invokes
+
+|Item|Value|
+|-|-|
+|CheckId|CA1417|
+|Category|Microsoft.Interoperability|
+|Breaking change|Non-breaking|
+
+## Cause
+
+A [P/Invoke](/dotnet/standard/native-interop/pinvoke) string parameter is passed by value and marked with 
+<xref:System.Runtime.InteropServices.OutAttribute>.
+
+## Rule description
+
+The .NET runtime automatically performs [string interning](/dotnet/api/system.string.intern#remarks). If an interned string marked with <xref:System.Runtime.InteropServices.OutAttribute> is passed by value to a P/Invoke, the runtime can be destabilized.
+
+## How to fix violations
+
+If marshaling of modified string data back to the caller is required, pass the string by reference instead. Otherwise, the <xref:System.Runtime.InteropServices.OutAttribute> can be removed without any other changes.
+
+```csharp
+ // Violation
+[DllImport("MyLibrary")]
+private static extern void Foo([Out] string s);
+
+// Fixed: passed by reference
+[DllImport("MyLibrary")]
+private static extern void Foo(out string s);
+
+// Fixed: marshaling data back to caller is not required
+[DllImport("MyLibrary")]
+private static extern void Foo(string s);
+```
+
+## When to suppress warnings
+
+It is not safe to suppress a warning from this rule.
+
+## See also
+
+- [Interoperability warnings](interoperability-warnings.md)
+- [Native interoperability best practices](/dotnet/standard/native-interop/best-practices)
diff --git a/docs/code-quality/code-analysis-warnings-for-managed-code-by-checkid.md b/docs/code-quality/code-analysis-warnings-for-managed-code-by-checkid.md
@@ -100,6 +100,7 @@ f1_keywords:
 - CA1413
 - CA1414
 - CA1415
+- CA1417
 - CA1500
 - CA1501
 - CA1502
@@ -391,6 +392,7 @@ The following table lists Code Analysis warnings for managed code by the CheckId
 | CA1413 | [CA1413: Avoid non-public fields in COM visible value types](../code-quality/ca1413.md) | Nonpublic instance fields of COM-visible value types are visible to COM clients. Review the content of the fields for information that should not be exposed, or that will have unintended design or security effects. |
 | CA1414 | [CA1414: Mark boolean P/Invoke arguments with MarshalAs](../code-quality/ca1414.md) | The Boolean data type has multiple representations in unmanaged code. |
 | CA1415 | [CA1415: Declare P/Invokes correctly](../code-quality/ca1415.md) | This rule looks for operating system invoke method declarations that target [!INCLUDE[TLA2#tla_win32](../code-quality/includes/tla2sharptla_win32_md.md)] functions that have a pointer to an OVERLAPPED structure parameter and the corresponding managed parameter is not a pointer to a System.Threading.NativeOverlapped structure. |
+| CA1417 | [CA1417: Do not use `OutAttribute` on string parameters for P/Invokes](../code-quality/ca1417.md) | String parameters passed by value with the `OutAttribute` can destabilize the runtime if the string is an interned string. |
 | CA1500 | [CA1500: Variable names should not match field names](../code-quality/ca1500.md) | An instance method declares a parameter or a local variable whose name matches an instance field of the declaring type, leading to errors. |
 | CA1501 | [CA1501: Avoid excessive inheritance](../code-quality/ca1501.md) | A type is more than four levels deep in its inheritance hierarchy. Deeply nested type hierarchies can be difficult to follow, understand, and maintain. |
 | CA1502 | [CA1502: Avoid excessive complexity](../code-quality/ca1502.md) | This rule measures the number of linearly independent paths through the method, which is determined by the number and complexity of conditional branches. |

diff --git a/docs/code-quality/interoperability-warnings.md b/docs/code-quality/interoperability-warnings.md
@@ -39,3 +39,4 @@ Interoperability warnings support interaction with COM clients.
 | [CA1413: Avoid non-public fields in COM visible value types](../code-quality/ca1413.md) | Nonpublic instance fields of COM-visible value types are visible to COM clients. Review the content of the fields for information that should not be exposed, or that will have unintended design or security effects. |
 | [CA1414: Mark boolean P/Invoke arguments with MarshalAs](../code-quality/ca1414.md) | The Boolean data type has multiple representations in unmanaged code. |
 | [CA1415: Declare P/Invokes correctly](../code-quality/ca1415.md) | This rule looks for platform invoke method declarations that target [!INCLUDE[TLA2#tla_win32](../code-quality/includes/tla2sharptla_win32_md.md)] functions that have a pointer to an OVERLAPPED structure parameter and the corresponding managed parameter is not a pointer to a <xref:System.Threading.NativeOverlapped?displayProperty=fullName> structure. |
+| [CA1417: Do not use `OutAttribute` on string parameters for P/Invokes](../code-quality/ca1417.md) | String parameters passed by value with the `OutAttribute` can destabilize the runtime if the string is an interned string. |
diff --git a/docs/code-quality/toc.yml b/docs/code-quality/toc.yml
@@ -415,6 +415,8 @@
           href: ca1414.md
         - name: "CA1415: Declare P-Invokes correctly"
           href: ca1415.md
+        - name: "CA1417: Do not use OutAttribute on string parameters for P/Invokes"
+          href: ca1417.md
       - name: Maintainability warnings
         items:
         - name: Overview

diff --git a/docs/get-started/csharp/tutorial-editor.md b/docs/get-started/csharp/tutorial-editor.md
@@ -13,9 +13,9 @@ dev_langs:
 ms.workload:
 - dotnet
 ---
-# Learn to use the code editor
+# Learn to use the code editor with C#
 
-In this 10-minute introduction to the code editor in Visual Studio, we'll add code to a file to look at some of the ways that Visual Studio makes writing, navigating, and understanding code easier.
+In this 10-minute introduction to the code editor in Visual Studio, we'll add code to a file to look at some of the ways that Visual Studio makes writing, navigating, and understanding C# code easier.
 
 ::: moniker range="vs-2017"
 

diff --git a/docs/get-started/visual-basic/tutorial-editor.md b/docs/get-started/visual-basic/tutorial-editor.md
@@ -13,9 +13,9 @@ dev_langs:
 ms.workload:
 - dotnet
 ---
-# Learn to use the code editor
+# Learn to use the code editor with Visual Basic
 
-In this 10-minute introduction to the code editor in Visual Studio, we'll add code to a file to look at some of the ways that Visual Studio makes writing, navigating, and understanding code easier.
+In this 10-minute introduction to the code editor in Visual Studio, we'll add code to a file to look at some of the ways that Visual Studio makes writing, navigating, and understanding Visual Basic code easier.
 
 ::: moniker range="vs-2017"
 

diff --git a/docs/ide/signing-in-to-visual-studio.md b/docs/ide/signing-in-to-visual-studio.md
@@ -2,7 +2,7 @@
 title: Sign in to Visual Studio
 titleSuffix: ''
 ms.custom: seodec18
-ms.date: 03/10/2020
+ms.date: 07/24/2020
 ms.topic: conceptual
 ms.assetid: b9531c25-e4cf-43ae-b331-a9f31a8cd171
 author: ornellaalt
@@ -33,7 +33,7 @@ When you sign in, you enrich your Visual Studio experience. For example, after y
 Here's a full list of what you can expect and what you can do after you sign in:
 - **Extend the Visual Studio trial period** - You can use Visual Studio Professional or Visual Studio Enterprise for an additional 90 days, instead of being limited to the trial period of 30 days. For more information, see [Extend a trial version or update a license](../ide/how-to-unlock-visual-studio.md).
 
-- **Unlock the Visual Studio Community edition** - If your Community edition installation prompts you for a license, sign in to the IDE to unblock yourself.
+- **Continue using the Visual Studio Community edition** - If your Community edition installation prompts you for a license, sign in to the IDE to continue using Visual Studio Community for **free**. 
 
 - **Unlock Visual Studio if you use an account that's associated with a Visual Studio subscription or an Azure DevOps organization**. For detailed instructions, see [Extend a trial version or update a license](../ide/how-to-unlock-visual-studio.md).