Skip to content

Commit 1466ac0

Browse files
TaojunshenTaojunshen
authored
Merge pull request #2068 from MicrosoftDocs/master
5/21 AM Publish
2 parents 3714458 + bfd6468 commit 1466ac0

File tree

160 files changed

+1010
-969
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

160 files changed

+1010
-969
lines changed

‎docs/code-quality/ca2227-collection-properties-should-be-read-only.md

Lines changed: 25 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,15 @@ ms.assetid: 26967aaf-6fbe-438a-b4d3-ac579b5dc0f9
1414
author: gewarren
1515
ms.author: gewarren
1616
manager: douge
17+
dev_langs:
18+
- CSharp
19+
- VB
20+
- CPP
1721
ms.workload:
1822
- "multiple"
1923
---
2024
# CA2227: Collection properties should be read only
25+
2126
|||
2227
|-|-|
2328
|TypeName|CollectionPropertiesShouldBeReadOnly|
@@ -26,25 +31,31 @@ ms.workload:
2631
|Breaking Change|Breaking|
2732

2833
## Cause
29-
An externally visible writable property is a type that implements <xref:System.Collections.ICollection?displayProperty=fullName>. Arrays, indexers (properties with the name 'Item'), and permission sets are ignored by the rule.
3034

31-
## Rule Description
32-
A writable collection property allows a user to replace the collection with a completely different collection. A read-only property stops the collection from being replaced but still allows the individual members to be set. If replacing the collection is a goal, the preferred design pattern is to include a method to remove all the elements from the collection and a method to re-populate the collection. See the <xref:System.Collections.ArrayList.Clear%2A> and <xref:System.Collections.ArrayList.AddRange%2A> methods of the <xref:System.Collections.ArrayList?displayProperty=fullName> class for an example of this pattern.
35+
An externally visible, writable property is of a type that implements <xref:System.Collections.ICollection?displayProperty=fullName>. This rule ignores arrays, indexers (properties with the name 'Item'), and permission sets.
36+
37+
## Rule description
38+
39+
A writable collection property allows a user to replace the collection with a completely different collection. A read-only property stops the collection from being replaced, but still allows the individual members to be set. If replacing the collection is a goal, the preferred design pattern is to include a method to remove all the elements from the collection, and a method to repopulate the collection. See the <xref:System.Collections.ArrayList.Clear%2A> and <xref:System.Collections.ArrayList.AddRange%2A> methods of the <xref:System.Collections.ArrayList?displayProperty=fullName> class for an example of this pattern.
40+
41+
Both binary and XML serialization support read-only properties that are collections. The <xref:System.Xml.Serialization.XmlSerializer?displayProperty=fullName> class has specific requirements for types that implement <xref:System.Collections.ICollection> and <xref:System.Collections.IEnumerable?displayProperty=fullName> in order to be serializable.
3342

34-
Both binary and XML serialization support read-only properties that are collections. The <xref:System.Xml.Serialization.XmlSerializer?displayProperty=fullName> class has specific requirements for types that implement <xref:System.Collections.ICollection> and <xref:System.Collections.IEnumerable?displayProperty=fullName> in order to be serializable.
43+
## How to fix violations
3544

36-
## How to Fix Violations
37-
To fix a violation of this rule, make the property read-only and, if the design requires it, add methods to clear and re-populate the collection.
45+
To fix a violation of this rule, make the property read-only. If the design requires it, add methods to clear and repopulate the collection.
3846

39-
## When to Suppress Warnings
40-
Do not suppress a warning from this rule.
47+
## When to suppress warnings
48+
49+
Do not suppress warnings from this rule.
4150

4251
## Example
43-
The following example shows a type with a writable collection property and shows how the collection can be replaced directly. Additionally, the preferred manner of replacing a read-only collection property using `Clear` and `AddRange` methods is shown.
4452

45-
[!code-csharp[FxCop.Usage.PropertiesReturningCollections#1](../code-quality/codesnippet/CSharp/ca2227-collection-properties-should-be-read-only_1.cs)]
46-
[!code-vb[FxCop.Usage.PropertiesReturningCollections#1](../code-quality/codesnippet/VisualBasic/ca2227-collection-properties-should-be-read-only_1.vb)]
47-
[!code-cpp[FxCop.Usage.PropertiesReturningCollections#1](../code-quality/codesnippet/CPP/ca2227-collection-properties-should-be-read-only_1.cpp)]
53+
The following example shows a type with a writable collection property and shows how the collection can be replaced directly. Additionally, the preferred manner of replacing a read-only collection property using `Clear` and `AddRange` methods is shown.
54+
55+
[!code-csharp[FxCop.Usage.PropertiesReturningCollections#1](../code-quality/codesnippet/CSharp/ca2227-collection-properties-should-be-read-only_1.cs)]
56+
[!code-vb[FxCop.Usage.PropertiesReturningCollections#1](../code-quality/codesnippet/VisualBasic/ca2227-collection-properties-should-be-read-only_1.vb)]
57+
[!code-cpp[FxCop.Usage.PropertiesReturningCollections#1](../code-quality/codesnippet/CPP/ca2227-collection-properties-should-be-read-only_1.cpp)]
58+
59+
## Related rules
4860

49-
## Related Rules
50-
[CA1819: Properties should not return arrays](../code-quality/ca1819-properties-should-not-return-arrays.md)
61+
[CA1819: Properties should not return arrays](../code-quality/ca1819-properties-should-not-return-arrays.md)

‎docs/code-quality/codesnippet/CPP/ca2227-collection-properties-should-be-read-only_1.cpp

Lines changed: 31 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,45 @@
1+
#include "stdafx.h"
12
using namespace System;
23
using namespace System::Collections;
34

45
namespace UsageLibrary
56
{
6-
public ref class WritableCollection
7-
{
8-
public:
9-
// Violates the rule.
10-
property ArrayList^ SomeStrings;
11-
12-
WritableCollection()
13-
{
14-
SomeStrings = gcnew ArrayList(
15-
gcnew array<String^> {"IEnumerable", "ICollection", "IList"} );
16-
}
17-
};
7+
public ref class WritableCollection
8+
{
9+
public:
10+
property ArrayList^ SomeStrings
11+
{
12+
ArrayList^ get() { return someStrings; }
13+
14+
// This set accessor violates rule CA2227.
15+
// To fix the code, remove this set accessor.
16+
void set(ArrayList^ value) { someStrings = value; }
17+
}
18+
19+
WritableCollection()
20+
{
21+
someStrings = gcnew ArrayList(gcnew array<String^> {"one", "two", "three"});
22+
}
23+
24+
private:
25+
ArrayList ^ someStrings;
26+
};
1827
}
1928

2029
using namespace UsageLibrary;
2130

2231
void main()
2332
{
24-
ArrayList^ newCollection = gcnew ArrayList(
25-
gcnew array<String^> {"a", "new", "collection"} );
33+
ArrayList^ newCollection = gcnew ArrayList(gcnew array<String^> {"a", "new", "collection"});
34+
35+
WritableCollection^ collection = gcnew WritableCollection();
2636

27-
// strings is directly replaced with newCollection.
28-
WritableCollection^ collection = gcnew WritableCollection();
29-
collection->SomeStrings = newCollection;
37+
// This line of code demonstrates how the entire collection
38+
// can be replaced by a property that's not read only.
39+
collection->SomeStrings = newCollection;
3040

31-
// newCollection is added to the cleared strings collection.
32-
collection->SomeStrings->Clear();
33-
collection->SomeStrings->AddRange(newCollection);
41+
// If the intent is to replace an entire collection,
42+
// implement and/or use the Clear() and AddRange() methods instead.
43+
collection->SomeStrings->Clear();
44+
collection->SomeStrings->AddRange(newCollection);
3445
}

‎docs/code-quality/codesnippet/CSharp/ca2227-collection-properties-should-be-read-only_1.cs

Lines changed: 30 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,40 @@
1-
using System;
21
using System.Collections;
32

4-
namespace UsageLibrary
3+
namespace csharp_code_analysis_examples
54
{
6-
public class WritableCollection
7-
{
8-
ArrayList strings;
5+
public class WritableCollection
6+
{
7+
public ArrayList SomeStrings
8+
{
9+
get;
910

10-
public ArrayList SomeStrings
11-
{
12-
get { return strings; }
11+
// This set accessor violates rule CA2227.
12+
// To fix the code, remove this set accessor.
13+
set;
14+
}
1315

14-
// Violates the rule.
15-
set { strings = value; }
16-
}
16+
public WritableCollection()
17+
{
18+
SomeStrings = new ArrayList(new string[] { "one", "two", "three" });
19+
}
20+
}
1721

18-
public WritableCollection()
19-
{
20-
strings = new ArrayList(
21-
new string[] {"IEnumerable", "ICollection", "IList"} );
22-
}
23-
}
22+
class ReplaceWritableCollection
23+
{
24+
static void Main()
25+
{
26+
ArrayList newCollection = new ArrayList(new string[] { "a", "new", "collection" });
2427

25-
class ReplaceWritableCollection
26-
{
27-
static void Main()
28-
{
29-
ArrayList newCollection = new ArrayList(
30-
new string[] {"a", "new", "collection"} );
28+
WritableCollection collection = new WritableCollection();
3129

32-
// strings is directly replaced with newCollection.
33-
WritableCollection collection = new WritableCollection();
34-
collection.SomeStrings = newCollection;
30+
// This line of code demonstrates how the entire collection
31+
// can be replaced by a property that's not read only.
32+
collection.SomeStrings = newCollection;
3533

36-
// newCollection is added to the cleared strings collection.
37-
collection.SomeStrings.Clear();
38-
collection.SomeStrings.AddRange(newCollection);
39-
}
40-
}
34+
// If the intent is to replace an entire collection,
35+
// implement and/or use the Clear() and AddRange() methods instead.
36+
collection.SomeStrings.Clear();
37+
collection.SomeStrings.AddRange(newCollection);
38+
}
39+
}
4140
}

‎docs/code-quality/codesnippet/VisualBasic/ca2227-collection-properties-should-be-read-only_1.vb

Lines changed: 22 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,31 @@
1-
Imports System
2-
Imports System.Collections
1+
Public Class WritableCollection
32

4-
Namespace UsageLibrary
3+
' This property violates rule CA2227.
4+
' To fix the code, add the ReadOnly modifier to the property:
5+
' ReadOnly Property SomeStrings As ArrayList
6+
Property SomeStrings As ArrayList
57

6-
Public Class WritableCollection
7-
8-
Dim strings As ArrayList
8+
Sub New()
9+
SomeStrings = New ArrayList(New String() {"one", "two", "three"})
10+
End Sub
911

10-
Property SomeStrings As ArrayList
11-
Get
12-
Return strings
13-
End Get
12+
End Class
1413

15-
' Violates the rule.
16-
Set
17-
strings = Value
18-
End Set
19-
End Property
14+
Class ViolatingVersusPreferred
2015

21-
Sub New()
22-
strings = New ArrayList( _
23-
New String() {"IEnumerable", "ICollection", "IList"} )
24-
End Sub
16+
Shared Sub Main()
17+
Dim newCollection As New ArrayList(New String() {"a", "new", "collection"})
2518

26-
End Class
19+
Dim collection As New WritableCollection()
2720

28-
Class ViolatingVersusPreferred
21+
' This line of code demonstrates how the entire collection
22+
' can be replaced by a property that's not read only.
23+
collection.SomeStrings = newCollection
2924

30-
Shared Sub Main()
31-
Dim newCollection As New ArrayList( _
32-
New String() {"a", "new", "collection"} )
25+
' If the intent is to replace an entire collection,
26+
' implement and/or use the Clear() and AddRange() methods instead.
27+
collection.SomeStrings.Clear()
28+
collection.SomeStrings.AddRange(newCollection)
29+
End Sub
3330

34-
' strings is directly replaced with newCollection.
35-
Dim collection As New WritableCollection()
36-
collection.SomeStrings = newCollection
37-
38-
' newCollection is added to the cleared strings collection.
39-
collection.SomeStrings.Clear()
40-
collection.SomeStrings.AddRange(newCollection)
41-
End Sub
42-
43-
End Class
44-
45-
End Namespace
31+
End Class

‎docs/deployment/TOC.md

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -8,26 +8,26 @@
88
## [Deploy to Azure](quickstart-deploy-to-azure.md)
99
# Tutorials
1010
## .NET
11-
### [Deploy a .NET Core Application with the Publish tool](/dotnet/core/deploying/deploy-with-vs)
12-
### [Package a desktop app for Microsoft Store (Desktop Bridge)](/windows/uwp/porting/desktop-to-uwp-packaging-dot-net)
11+
### [Deploy a .NET Core Application with the Publish tool](/dotnet/core/deploying/deploy-with-vs?toc=/visualstudio/deployment/toc.json&bc=/visualstudio/deployment/_breadcrumb/toc.json)
12+
### [Package a desktop app for Microsoft Store (Desktop Bridge)](/windows/uwp/porting/desktop-to-uwp-packaging-dot-net?toc=/visualstudio/deployment/toc.json&bc=/visualstudio/deployment/_breadcrumb/toc.json)
1313
### [Deploy a desktop app using ClickOnce](how-to-publish-a-clickonce-application-using-the-publish-wizard.md)
1414
### [Building ClickOnce Applications from the Command Line](building-clickonce-applications-from-the-command-line.md)
1515
## ASP.NET
16-
### [Publish an ASP.NET Core app to Azure](/aspnet/core/tutorials/publish-to-azure-webapp-using-vs)
16+
### [Publish an ASP.NET Core app to Azure](/aspnet/core/tutorials/publish-to-azure-webapp-using-vs?toc=/visualstudio/deployment/toc.json&bc=/visualstudio/deployment/_breadcrumb/toc.json)
1717
### [Import publish settings and deploy to Azure](tutorial-import-publish-settings-azure.md)
1818
### [Import publish settings and deploy to IIS](tutorial-import-publish-settings-iis.md)
19-
### [Continuous deployment of ASP.NET Core to Azure with Git](/aspnet/core/publishing/azure-continuous-deployment)
20-
### [Deploy ASP.NET to IIS](/iis/get-started/whats-new-in-iis-8/iis-80-using-aspnet-35-and-aspnet-45)
19+
### [Continuous deployment of ASP.NET Core to Azure with Git](/aspnet/core/publishing/azure-continuous-deployment?toc=/visualstudio/deployment/toc.json&bc=/visualstudio/deployment/_breadcrumb/toc.json)
20+
### [Deploy ASP.NET to IIS](/iis/get-started/whats-new-in-iis-8/iis-80-using-aspnet-35-and-aspnet-45?toc=/visualstudio/deployment/toc.json&bc=/visualstudio/deployment/_breadcrumb/toc.json)
2121
## Native
22-
### [Deployment in Visual C++](/cpp/ide/deployment-in-visual-cpp)
23-
### [Package a desktop app for Microsoft Store (Desktop Bridge)](/windows/uwp/porting/desktop-to-uwp-packaging-dot-net)
24-
### [Deploy a native app using ClickOnce](/cpp/ide/clickonce-deployment-for-visual-cpp-applications)
22+
### [Deployment in Visual C++...](/cpp/ide/deployment-in-visual-cpp)
23+
### [Package a desktop app for Microsoft Store (Desktop Bridge)](/windows/uwp/porting/desktop-to-uwp-packaging-dot-net?toc=/visualstudio/deployment/toc.json&bc=/visualstudio/deployment/_breadcrumb/toc.json)
24+
### [Deploy a native app using ClickOnce...](/cpp/ide/clickonce-deployment-for-visual-cpp-applications)
2525
## UWP
26-
### [Package a UWP app by using Visual Studio](/windows/uwp/packaging/packaging-uwp-apps)
26+
### [Package a UWP app by using Visual Studio](/windows/uwp/packaging/packaging-uwp-apps?toc=/visualstudio/deployment/toc.json&bc=/visualstudio/deployment/_breadcrumb/toc.json)
2727
## Node.js
28-
### [Publish to Azure Website using Web Deploy](https://github.com/Microsoft/nodejstools/wiki/Publish-to-Azure-Website-using-Web-Deploy)
28+
### [Publish to Azure Website using Web Deploy](https://github.com/Microsoft/nodejstools/wiki/Publish-to-Azure-Website-using-Web-Deploy?toc=/visualstudio/deployment/toc.json&bc=/visualstudio/deployment/_breadcrumb/toc.json)
2929
## Python
30-
### [Publish to Azure App Service](/visualstudio/python/publishing-python-web-applications-to-azure-from-visual-studio)
30+
### [Publish to Azure App Service](/visualstudio/python/publishing-python-web-applications-to-azure-from-visual-studio?toc=/visualstudio/deployment/toc.json&bc=/visualstudio/deployment/_breadcrumb/toc.json)
3131
# How-to guides
3232
## [ClickOnce Security and Deployment](clickonce-security-and-deployment.md)
3333
### [Choosing a ClickOnce Deployment Strategy](choosing-a-clickonce-deployment-strategy.md)

‎docs/deployment/_breadcrumb/toc.yml

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
- name: Docs
2+
tocHref: /
3+
topicHref: /
4+
items:
5+
- name: Visual Studio
6+
tocHref: /visualstudio/
7+
topicHref: /visualstudio/ide/
8+
items:
9+
- name: Deployment
10+
tocHref: /visualstudio/deployment/
11+
topicHref: /visualstudio/deployment/deploying-applications-services-and-components

‎docs/deployment/quickstart-deploy-to-local-folder.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,6 @@ Deploy the published files in any way you like. For example, you can package the
6767

6868
## Next steps
6969

70-
- [Deploy a .NET Core Application with the Publish tool](/dotnet/core/deploying/deploy-with-vs)
71-
- [Package a desktop app for Microsoft Store (Desktop Bridge)](/windows/uwp/porting/desktop-to-uwp-packaging-dot-net)
72-
- (.NET) [Deploy the .NET Framework and applications](/dotnet/framework/deployment/)
70+
- [Deploy a .NET Core Application with the Publish tool](/dotnet/core/deploying/deploy-with-vs?toc=/visualstudio/deployment/toc.json&bc=/visualstudio/deployment/_breadcrumb/toc.json)
71+
- [Package a desktop app for Microsoft Store (Desktop Bridge)](/windows/uwp/porting/desktop-to-uwp-packaging-dot-net?toc=/visualstudio/deployment/toc.json&bc=/visualstudio/deployment/_breadcrumb/toc.json)
72+
- (.NET) [Deploy the .NET Framework and applications...](/dotnet/framework/deployment/)

‎docs/ide/class-designer/designing-and-viewing-classes-and-types.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,5 +53,5 @@ After you have fine-tuned one or more class diagrams, you can copy them into Mic
5353
5454
## See also
5555

56-
- [Write code in the editor](../writing-code-in-the-code-and-text-editor.md)
56+
- [Features of the code editor](../writing-code-in-the-code-and-text-editor.md)
5757
- [Map dependencies across your solutions](../../modeling/map-dependencies-across-your-solutions.md)

‎docs/ide/create-portable-custom-editor-options.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -157,4 +157,4 @@ You can control the scope of your EditorConfig conventions by setting the ```roo
157157
- [.NET naming conventions](../ide/editorconfig-naming-conventions.md)
158158
- [Supporting EditorConfig for a language service](../extensibility/supporting-editorconfig.md)
159159
- [EditorConfig.org](http://editorconfig.org/)
160-
- [Writing code in the editor](writing-code-in-the-code-and-text-editor.md)
160+
- [Features of the code editor](writing-code-in-the-code-and-text-editor.md)

‎docs/ide/customize-build-and-debug-tasks-in-visual-studio.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -310,4 +310,4 @@ Settings read from the *.gitignore* file are applied to its parent directory and
310310
- [Open Folder projects for C++](/cpp/ide/non-msbuild-projects)
311311
- [CMake projects in C++](/cpp/ide/cmake-tools-for-visual-cpp)
312312
- [NMAKE reference](/cpp/build/nmake-reference)
313-
- [Writing code in the code and text editor](../ide/writing-code-in-the-code-and-text-editor.md)
313+
- [Features of the code editor](../ide/writing-code-in-the-code-and-text-editor.md)

‎docs/ide/customizing-the-editor.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ For more information about the text editor options, see [Text Editor Options dia
2525
## See also
2626

2727
- [Quickstart: Personalize the Visual Studio IDE and editor](../ide/quickstart-personalize-the-ide.md)
28-
- [Writing code](../ide/writing-code-in-the-code-and-text-editor.md)
28+
- [Features of the code editor](../ide/writing-code-in-the-code-and-text-editor.md)
2929
- [Setting bookmarks in code](../ide/setting-bookmarks-in-code.md)
3030
- [General, Environment, Options dialog box](../ide/reference/general-environment-options-dialog-box.md)
3131
- [Documents, Environment, Options dialog box](../ide/reference/documents-environment-options-dialog-box.md)

‎docs/ide/encodings-and-line-breaks.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,4 +51,4 @@ You can use the **File** > **Advanced Save Options** dialog box to determine the
5151
5252
## See also
5353

54-
- [Writing code in the editor](../ide/writing-code-in-the-code-and-text-editor.md)
54+
- [Features of the code editor](../ide/writing-code-in-the-code-and-text-editor.md)

‎docs/ide/find-code-changes-and-other-history-with-codelens.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -319,4 +319,4 @@ To use the keyboard:
319319

320320
## See also
321321

322-
- [Writing code in the editor](../ide/writing-code-in-the-code-and-text-editor.md)
322+
- [Features of the code editor](../ide/writing-code-in-the-code-and-text-editor.md)

0 commit comments

Comments
 (0)