diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index ac33ac33de873..7322ff6bcdd1e 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -1,5 +1,245 @@ { "redirections": [ + { + "source_path": "docs/standard/design-guidelines/abstract-class.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/abstract-class", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/abstractions-abstract-types-and-interfaces.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/abstractions-abstract-types-and-interfaces", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/arrays.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/arrays", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/attributes.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/attributes", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/base-classes-for-implementing-abstractions.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/base-classes-for-implementing-abstractions", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/capitalization-conventions.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/capitalization-conventions", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/choosing-between-class-and-struct.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/choosing-between-class-and-struct", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/common-design-patterns.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/common-design-patterns", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/constructor.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/constructor", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/dependency-properties.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/dependency-properties", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/designing-for-extensibility.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/designing-for-extensibility", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/enum.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/enum", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/equality-operators.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/equality-operators", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/event.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/event", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/events-and-callbacks.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/events-and-callbacks", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/exception-throwing.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/exception-throwing", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/exceptions-and-performance.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/exceptions-and-performance", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/exceptions.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/exceptions", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/extension-methods.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/extension-methods", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/field.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/field", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/general-naming-conventions.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/general-naming-conventions", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/guidelines-for-collections.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/guidelines-for-collections", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/index.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/index", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/interface.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/interface", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/member-overloading.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/member-overloading", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/member.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/member", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/names-of-assemblies-and-dlls.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/names-of-assemblies-and-dlls", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/names-of-classes-structs-and-interfaces.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/names-of-classes-structs-and-interfaces", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/names-of-namespaces.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/names-of-namespaces", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/names-of-type-members.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/names-of-type-members", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/naming-guidelines.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/naming-guidelines", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/naming-parameters.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/naming-parameters", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/naming-resources.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/naming-resources", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/nested-types.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/nested-types", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/operator-overloads.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/operator-overloads", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/parameter-design.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/parameter-design", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/property.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/property", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/protected-members.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/protected-members", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/sealing.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/sealing", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/serialization.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/serialization", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/static-class.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/static-class", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/struct.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/struct", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/system-xml-usage.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/system-xml-usage", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/type.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/type", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/unsealed-classes.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/unsealed-classes", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/usage-guidelines.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/usage-guidelines", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/using-standard-exception-types.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/using-standard-exception-types", + "redirect_document_id": false + }, + { + "source_path": "docs/standard/design-guidelines/virtual-members.md", + "redirect_url": "/previous-versions/dotnet/standard/design-guidelines/virtual-members", + "redirect_document_id": false + }, { "source_path_from_root": "/docs/about/index.md", "redirect_url": "/dotnet/standard/index" diff --git a/docs/architecture/porting-existing-aspnet-apps/more-migration-scenarios.md b/docs/architecture/porting-existing-aspnet-apps/more-migration-scenarios.md index 1649e1fa1bfba..31464a14767dc 100644 --- a/docs/architecture/porting-existing-aspnet-apps/more-migration-scenarios.md +++ b/docs/architecture/porting-existing-aspnet-apps/more-migration-scenarios.md @@ -2,7 +2,7 @@ title: More migration scenarios description: This section describes additional migration scenarios and techniques for upgrading .NET Framework apps to .NET Core / .NET 6. author: ardalis -ms.date: 02/11/2021 +ms.date: 12/10/2021 --- # More migration scenarios @@ -237,7 +237,7 @@ ASP.NET Core uses route constraints to help ensure requests are routed properly [Route("/customer/{id:int}")] ``` -The `:int` after the `id` route parameter constrains the value to match the the `int` type. One benefit of using route constraints is that they allow for two otherwise-identical routes to exist where the parameters differ only by their type. This allows for the equivalent of [method overloading](../../standard/design-guidelines/member-overloading.md) of routes based solely on parameter type. +The `:int` after the `id` route parameter constrains the value to match the the `int` type. One benefit of using route constraints is that they allow for two otherwise-identical routes to exist where the parameters differ only by their type. This allows for the equivalent of method overloading of routes based solely on parameter type. The set of route constraints, their syntax, and usage is very similar between all three approaches. Custom route constraints are fairly rare in customer applications. If your app uses a custom route constraint and needs to port to ASP.NET Core, the docs include examples showing [how to create custom route constraints in ASP.NET Core](/aspnet/core/fundamentals/routing#custom-route-constraints). Essentially all that's required is to implement `IRouteConstraint` and its `Match` method, and then add the custom constraint when configuring routing for the app: diff --git a/docs/core/extensions/high-performance-logging.md b/docs/core/extensions/high-performance-logging.md index b28a70e2e8f39..8cf3e21196eca 100644 --- a/docs/core/extensions/high-performance-logging.md +++ b/docs/core/extensions/high-performance-logging.md @@ -23,7 +23,7 @@ The sample app demonstrates fe Use [Define(LogLevel, EventId, String)](xref:Microsoft.Extensions.Logging.LoggerMessage.Define%2A) to create an delegate for logging a message. overloads permit passing up to six type parameters to a named format string (template). -The string provided to the method is a template and not an interpolated string. Placeholders are filled in the order that the types are specified. Placeholder names in the template should be descriptive and consistent across templates. They serve as property names within structured log data. We recommend [Pascal casing](../../standard/design-guidelines/capitalization-conventions.md) for placeholder names. For example, `{Item}`, `{DateTime}`. +The string provided to the method is a template and not an interpolated string. Placeholders are filled in the order that the types are specified. Placeholder names in the template should be descriptive and consistent across templates. They serve as property names within structured log data. We recommend pascal casing for placeholder names. For example, `{Item}`, `{DateTime}`. Each log message is an held in a static field created by [LoggerMessage.Define](xref:Microsoft.Extensions.Logging.LoggerMessage.Define%2A). For example, the sample app creates a field to describe a log message for the processing of work items: @@ -86,7 +86,7 @@ info: WorkerServiceOptions.Example.Worker[1] The [DefineScope(string)](xref:Microsoft.Extensions.Logging.LoggerMessage.DefineScope%2A) method creates a delegate for defining a [log scope](logging.md#log-scopes). overloads permit passing up to three type parameters to a named format string (template). -As is the case with the method, the string provided to the method is a template and not an interpolated string. Placeholders are filled in the order that the types are specified. Placeholder names in the template should be descriptive and consistent across templates. They serve as property names within structured log data. We recommend [Pascal casing](../../standard/design-guidelines/capitalization-conventions.md) for placeholder names. For example, `{Item}`, `{DateTime}`. +As is the case with the method, the string provided to the method is a template and not an interpolated string. Placeholders are filled in the order that the types are specified. Placeholder names in the template should be descriptive and consistent across templates. They serve as property names within structured log data. We recommend pascal casing for placeholder names. For example, `{Item}`, `{DateTime}`. Define a [log scope](logging.md#log-scopes) to apply to a series of log messages using the method. Enable `IncludeScopes` in the console logger section of *appsettings.json*: diff --git a/docs/csharp/fundamentals/coding-style/identifier-names.md b/docs/csharp/fundamentals/coding-style/identifier-names.md index 80c8005d37b1b..56ed94f80faf3 100644 --- a/docs/csharp/fundamentals/coding-style/identifier-names.md +++ b/docs/csharp/fundamentals/coding-style/identifier-names.md @@ -1,21 +1,22 @@ --- title: "Identifier names" description: "Learn the rules for valid identifier names in the C# programming language." -ms.date: 08/21/2018 +ms.date: 12/10/2021 --- + # Identifier names An **identifier** is the name you assign to a type (class, interface, struct, delegate, or enum), member, variable, or namespace. Valid identifiers must follow these rules: - Identifiers must start with a letter, or `_`. - Identifiers may contain Unicode letter characters, decimal digit characters, Unicode connecting characters, Unicode combining characters, or Unicode formatting characters. For more information on Unicode categories, see the [Unicode Category Database](https://www.unicode.org/reports/tr44/). -You can declare identifiers that match C# keywords by using the `@` prefix on the identifier. The `@` is not part of the identifier name. For example, `@if` declares an identifier named `if`. These [verbatim identifiers](../../language-reference/tokens/verbatim.md) are primarily for interoperability with identifiers declared in other languages. + You can declare identifiers that match C# keywords by using the `@` prefix on the identifier. The `@` is not part of the identifier name. For example, `@if` declares an identifier named `if`. These [verbatim identifiers](../../language-reference/tokens/verbatim.md) are primarily for interoperability with identifiers declared in other languages. For a complete definition of valid identifiers, see the [Identifiers topic in the C# Language Specification](~/_csharplang/spec/lexical-structure.md#identifiers). ## Naming conventions -In addition to the rules, there are many identifier [naming conventions](../../../standard/design-guidelines/naming-guidelines.md) used throughout the .NET APIs. By convention, C# programs use `PascalCase` for type names, namespaces, and all public members. In addition, the following conventions are common: +In addition to the rules, there are many identifier naming conventions used throughout the .NET APIs. By convention, C# programs use `PascalCase` for type names, namespaces, and all public members. In addition, the following conventions are common: - Interface names start with a capital `I`. - Attribute types end with the word `Attribute`. @@ -24,8 +25,8 @@ In addition to the rules, there are many identifier [naming conventions](../../. ## C# Language Specification -[!INCLUDE[CSharplangspec](~/includes/csharplangspec-md.md)] - +[!INCLUDE[CSharplangspec](~/includes/csharplangspec-md.md)] + ## See also - [C# Programming Guide](../../programming-guide/index.md) @@ -35,3 +36,4 @@ In addition to the rules, there are many identifier [naming conventions](../../. - [Namespaces](../types/namespaces.md) - [Interfaces](../types/interfaces.md) - [Delegates](../../programming-guide/delegates/index.md) +- [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines) diff --git a/docs/csharp/language-reference/builtin-types/enum.md b/docs/csharp/language-reference/builtin-types/enum.md index 8003766fbc2af..34006b6d1ea96 100644 --- a/docs/csharp/language-reference/builtin-types/enum.md +++ b/docs/csharp/language-reference/builtin-types/enum.md @@ -83,7 +83,6 @@ For more information, see the following sections of the [C# language specificati - [C# reference](../index.md) - [Enumeration format strings](../../../standard/base-types/enumeration-format-strings.md) -- [Design guidelines - Enum design](../../../standard/design-guidelines/enum.md) -- [Design guidelines - Enum naming conventions](../../../standard/design-guidelines/names-of-classes-structs-and-interfaces.md#naming-enumerations) - [`switch` expression](../operators/switch-expression.md) - [`switch` statement](../statements/selection-statements.md#the-switch-statement) +- [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines) diff --git a/docs/csharp/language-reference/builtin-types/record.md b/docs/csharp/language-reference/builtin-types/record.md index e3a2bc1115146..e33900297b247 100644 --- a/docs/csharp/language-reference/builtin-types/record.md +++ b/docs/csharp/language-reference/builtin-types/record.md @@ -1,7 +1,7 @@ --- title: "Records - C# reference" description: Learn about the record type in C# -ms.date: 09/30/2021 +ms.date: 12/10/2021 f1_keywords: - "record_CSharpKeyword" helpviewer_keywords: @@ -231,7 +231,6 @@ For more information about features introduced in C# 9 and later, see the follow ## See also - [C# reference](../index.md) -- [Design guidelines - Choosing between class and struct](../../../standard/design-guidelines/choosing-between-class-and-struct.md) -- [Design guidelines - Struct design](../../../standard/design-guidelines/struct.md) - [The C# type system](../../fundamentals/types/index.md) - [`with` expression](../operators/with-expression.md) +- [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines) diff --git a/docs/csharp/language-reference/builtin-types/struct.md b/docs/csharp/language-reference/builtin-types/struct.md index c86e414dc20bb..1b149b965a41c 100644 --- a/docs/csharp/language-reference/builtin-types/struct.md +++ b/docs/csharp/language-reference/builtin-types/struct.md @@ -1,7 +1,7 @@ --- title: "Structure types - C# reference" description: Learn about the struct type in C# -ms.date: 09/15/2021 +ms.date: 12/10/2021 f1_keywords: - "struct_CSharpKeyword" helpviewer_keywords: @@ -182,6 +182,5 @@ For more information about features introduced in C# 7.2 and later, see the foll ## See also - [C# reference](../index.md) -- [Design guidelines - Choosing between class and struct](../../../standard/design-guidelines/choosing-between-class-and-struct.md) -- [Design guidelines - Struct design](../../../standard/design-guidelines/struct.md) - [The C# type system](../../fundamentals/types/index.md) +- [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines) diff --git a/docs/csharp/language-reference/operators/operator-overloading.md b/docs/csharp/language-reference/operators/operator-overloading.md index 89fd042aa899c..a44e076277bbe 100644 --- a/docs/csharp/language-reference/operators/operator-overloading.md +++ b/docs/csharp/language-reference/operators/operator-overloading.md @@ -1,7 +1,7 @@ --- title: "Operator overloading - C# reference" description: "Learn how to overload a C# operator and which C# operators are overloadable." -ms.date: 07/05/2019 +ms.date: 12/10/2021 f1_keywords: - "operator_CSharpKeyword" - operator @@ -59,6 +59,6 @@ For more information, see the following sections of the [C# language specificati - [C# reference](../index.md) - [C# operators and expressions](index.md) - [User-defined conversion operators](user-defined-conversion-operators.md) -- [Design guidelines - Operator overloads](../../../standard/design-guidelines/operator-overloads.md) -- [Design guidelines - Equality operators](../../../standard/design-guidelines/equality-operators.md) +- [Equality operators (C# reference)](equality-operators.md) - [Why are overloaded operators always static in C#?](/archive/blogs/ericlippert/why-are-overloaded-operators-always-static-in-c) +- [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines) diff --git a/docs/csharp/language-reference/operators/user-defined-conversion-operators.md b/docs/csharp/language-reference/operators/user-defined-conversion-operators.md index 7160b94c49a17..5f613de06379d 100644 --- a/docs/csharp/language-reference/operators/user-defined-conversion-operators.md +++ b/docs/csharp/language-reference/operators/user-defined-conversion-operators.md @@ -1,7 +1,7 @@ --- title: "User-defined conversion operators - C# reference" description: "Learn how to define custom implicit and explicit type conversions in C#." -ms.date: 07/09/2019 +ms.date: 12/10/2021 f1_keywords: - "explicit_CSharpKeyword" - "implicit_CSharpKeyword" @@ -45,5 +45,5 @@ For more information, see the following sections of the [C# language specificati - [Operator overloading](operator-overloading.md) - [Type-testing and cast operators](type-testing-and-cast.md) - [Casting and type conversion](../../programming-guide/types/casting-and-type-conversions.md) -- [Design guidelines - Conversion operators](../../../standard/design-guidelines/operator-overloads.md#conversion-operators) - [Chained user-defined explicit conversions in C#](/archive/blogs/ericlippert/chained-user-defined-explicit-conversions-in-c) +- [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines) diff --git a/docs/csharp/misc/cs0659.md b/docs/csharp/misc/cs0659.md index c38429c8158cf..8c0549ac7c022 100644 --- a/docs/csharp/misc/cs0659.md +++ b/docs/csharp/misc/cs0659.md @@ -1,7 +1,7 @@ --- description: "Compiler Warning (level 3) CS0659" title: "Compiler Warning (level 3) CS0659" -ms.date: 09/05/2018 +ms.date: 12/10/2021 f1_keywords: - "CS0659" helpviewer_keywords: @@ -36,5 +36,5 @@ class Test2 - - -- [Equality Operators](../../standard/design-guidelines/equality-operators.md) +- [Equality operators (C# reference)](../language-reference/operators/equality-operators.md) - [Implementing the Equals Method](/previous-versions/dotnet/netframework-4.0/336aedhh(v=vs.100)) diff --git a/docs/csharp/programming-guide/classes-and-structs/static-constructors.md b/docs/csharp/programming-guide/classes-and-structs/static-constructors.md index 662e0ed939c2f..054430c414461 100644 --- a/docs/csharp/programming-guide/classes-and-structs/static-constructors.md +++ b/docs/csharp/programming-guide/classes-and-structs/static-constructors.md @@ -1,7 +1,7 @@ --- title: "Static Constructors - C# Programming Guide" description: A static constructor in C# initializes static data or performs an action done only once. It runs before the first instance is created or static members are referenced. -ms.date: 03/30/2021 +ms.date: 12/10/2021 helpviewer_keywords: - "static constructors [C#]" - "constructors [C#], static" @@ -65,5 +65,5 @@ For more information, see the [Static constructors](~/_csharplang/spec/classes.m - [Constructors](./constructors.md) - [Static Classes and Static Class Members](./static-classes-and-static-class-members.md) - [Finalizers](./finalizers.md) -- [Constructor Design Guidelines](../../../standard/design-guidelines/constructor.md#type-constructor-guidelines) - [Security Warning - CA2121: Static constructors should be private](/visualstudio/code-quality/ca2121-static-constructors-should-be-private) +- [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines) diff --git a/docs/csharp/tutorials/console-webapiclient.md b/docs/csharp/tutorials/console-webapiclient.md index e20897e060268..2ae0bf7781918 100644 --- a/docs/csharp/tutorials/console-webapiclient.md +++ b/docs/csharp/tutorials/console-webapiclient.md @@ -1,7 +1,7 @@ --- title: "Tutorial: Make HTTP requests in a .NET console app using C#" description: Learn how to make HTTP requests to a REST web service and deserialize JSON responses. This tutorial creates a .NET console and uses C#. -ms.date: 04/21/2021 +ms.date: 12/10/2021 --- # Tutorial: Make HTTP requests in a .NET console app using C\# @@ -168,7 +168,7 @@ The following steps convert the JSON response into C# objects. You use the in the `ProcessRepositories` method with the following lines: diff --git a/docs/fsharp/style-guide/component-design-guidelines.md b/docs/fsharp/style-guide/component-design-guidelines.md index 9c4717f182d01..f37709165c5b9 100644 --- a/docs/fsharp/style-guide/component-design-guidelines.md +++ b/docs/fsharp/style-guide/component-design-guidelines.md @@ -1,7 +1,7 @@ --- title: F# component design guidelines description: Learn the guidelines for writing F# components intended for consumption by other callers. -ms.date: 05/14/2018 +ms.date: 12/10/2021 --- # F# component design guidelines @@ -20,7 +20,7 @@ This document looks at some of the issues related to F# component design and cod Techniques described in this article follow the [Five principles of good F# code](index.md#five-principles-of-good-f-code), and thus utilize both functional and object programming as appropriate. -Regardless of the methodology, the component and library designer faces a number of practical and prosaic issues when trying to craft an API that is most easily usable by developers. Conscientious application of the [.NET Library Design Guidelines](../../standard/design-guidelines/index.md) will steer you towards creating a consistent set of APIs that are pleasant to consume. +Regardless of the methodology, the component and library designer faces a number of practical and prosaic issues when trying to craft an API that is most easily usable by developers. Conscientious application of the [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines) will steer you towards creating a consistent set of APIs that are pleasant to consume. ## General guidelines @@ -28,7 +28,7 @@ There are a few universal guidelines that apply to F# libraries, regardless of t ### Learn the .NET Library Design Guidelines -Regardless of the kind of F# coding you are doing, it is valuable to have a working knowledge of the [.NET Library Design Guidelines](../../standard/design-guidelines/index.md). Most other F# and .NET programmers will be familiar with these guidelines, and expect .NET code to conform to them. +Regardless of the kind of F# coding you are doing, it is valuable to have a working knowledge of the [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines). Most other F# and .NET programmers will be familiar with these guidelines, and expect .NET code to conform to them. The .NET Library Design Guidelines provide general guidance regarding naming, designing classes and interfaces, member design (properties, methods, events, etc.) and more, and are a useful first point of reference for a variety of design guidance. @@ -444,7 +444,7 @@ However, the logical dot-notation operations on this type are not the same as th ## Guidelines for libraries for Use from other .NET Languages -When designing libraries for use from other .NET languages, it is important to adhere to the [.NET Library Design Guidelines](../../standard/design-guidelines/index.md). In this document, these libraries are labeled as vanilla .NET libraries, as opposed to F#-facing libraries that use F# constructs without restriction. Designing vanilla .NET libraries means providing familiar and idiomatic APIs consistent with the rest of the .NET Framework by minimizing the use of F#-specific constructs in the public API. The rules are explained in the following sections. +When designing libraries for use from other .NET languages, it is important to adhere to the [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines). In this document, these libraries are labeled as vanilla .NET libraries, as opposed to F#-facing libraries that use F# constructs without restriction. Designing vanilla .NET libraries means providing familiar and idiomatic APIs consistent with the rest of the .NET Framework by minimizing the use of F#-specific constructs in the public API. The rules are explained in the following sections. ### Namespace and Type design (for libraries for use from other .NET Languages) diff --git a/docs/fsharp/style-guide/conventions.md b/docs/fsharp/style-guide/conventions.md index c6cc6a52eddf8..75ce5829dfe13 100644 --- a/docs/fsharp/style-guide/conventions.md +++ b/docs/fsharp/style-guide/conventions.md @@ -1,7 +1,7 @@ --- title: F# coding conventions description: Learn general guidelines and idioms when writing F# code. -ms.date: 01/5/2021 +ms.date: 12/10/2021 --- # F# coding conventions @@ -199,7 +199,7 @@ In general, if you can model the different ways that something can **fail** in y Not all errors can be represented in a problem domain. These kinds of faults are *exceptional* in nature, hence the ability to raise and catch exceptions in F#. -First, it is recommended that you read the [Exception Design Guidelines](../../standard/design-guidelines/exceptions.md). These are also applicable to F#. +First, it is recommended that you read the [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines) section on Exceptions. These are also applicable to F#. The main constructs available in F# for the purposes of raising exceptions should be considered in the following order of preference: @@ -214,7 +214,7 @@ The main constructs available in F# for the purposes of raising exceptions shoul Use `nullArg`, `invalidArg`, and `invalidOp` as the mechanism to throw `ArgumentNullException`, `ArgumentException`, and `InvalidOperationException` when appropriate. -The `failwith` and `failwithf` functions should generally be avoided because they raise the base `Exception` type, not a specific exception. As per the [Exception Design Guidelines](../../standard/design-guidelines/exceptions.md), you want to raise more specific exceptions when you can. +The `failwith` and `failwithf` functions should generally be avoided because they raise the base `Exception` type, not a specific exception. As per the [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines), you want to raise more specific exceptions when you can. ### Use exception-handling syntax diff --git a/docs/fundamentals/code-analysis/categories.md b/docs/fundamentals/code-analysis/categories.md index 0776a14e6664f..1cb71bac2ec6c 100644 --- a/docs/fundamentals/code-analysis/categories.md +++ b/docs/fundamentals/code-analysis/categories.md @@ -1,7 +1,7 @@ --- title: Code analysis rule categories description: Learn the different .NET code analysis rule categories. -ms.date: 10/04/2021 +ms.date: 12/10/2021 ms.topic: reference helpviewer_keywords: - code analysis, categories @@ -18,7 +18,7 @@ The following table shows the different code analysis rule categories and provid | Category | Description | EditorConfig value | | - | - | - | | Code quality rules | This category encompasses the following miscellaneous rules: [IDE0051](style-rules/ide0051.md), [IDE0064](style-rules/ide0064.md), [IDE0076](style-rules/ide0076.md). | `dotnet_analyzer_diagnostic.category-CodeQuality.severity` | -| [Design rules](quality-rules/design-warnings.md) | Design rules support adherence to the [.NET Framework Design Guidelines](../../standard/design-guidelines/index.md). | `dotnet_analyzer_diagnostic.category-Design.severity` | +| [Design rules](quality-rules/design-warnings.md) | Design rules support adherence to the [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines). | `dotnet_analyzer_diagnostic.category-Design.severity` | | [Documentation rules](quality-rules/documentation-warnings.md) | Documentation rules support writing well-documented libraries through the correct use of XML documentation comments for externally visible APIs. | `dotnet_analyzer_diagnostic.category-Documentation.severity` | | [Globalization rules](quality-rules/globalization-warnings.md) | Globalization rules support world-ready libraries and applications. | `dotnet_analyzer_diagnostic.category-Globalization.severity` | | [Portability and interoperability rules](quality-rules/interoperability-warnings.md) | Portability rules support portability across different platforms. Interoperability rules support interaction with COM clients. | `dotnet_analyzer_diagnostic.category-Interoperability.severity` | diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1018.md b/docs/fundamentals/code-analysis/quality-rules/ca1018.md index 1c7ea5d9d03de..cfa97e15524ae 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1018.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1018.md @@ -1,7 +1,7 @@ --- title: "CA1018: Mark attributes with AttributeUsageAttribute (code analysis)" description: "Learn about code analysis rule CA1018: Mark attributes with AttributeUsageAttribute" -ms.date: 11/04/2016 +ms.date: 12/10/2021 ms.topic: reference f1_keywords: - CA1018 @@ -56,4 +56,4 @@ The following example defines two attributes. `BadCodeMaintainerAttribute` incor ## See also -- [Attributes](../../../standard/design-guidelines/attributes.md) +- [Attributes (C#)](../../../csharp/programming-guide/concepts/attributes/index.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1019.md b/docs/fundamentals/code-analysis/quality-rules/ca1019.md index 546a12bd00655..77e96032e45e1 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1019.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1019.md @@ -1,7 +1,7 @@ --- title: "CA1019: Define accessors for attribute arguments (code analysis)" description: "Learn about code analysis rule CA1019: Define accessors for attribute arguments" -ms.date: 11/04/2016 +ms.date: 12/10/2021 ms.topic: reference f1_keywords: - CA1019 @@ -73,4 +73,4 @@ The following example shows how to apply the custom attribute to two properties: ## See also -- [Attributes](../../../standard/design-guidelines/attributes.md) +- [Attributes (C#)](../../../csharp/programming-guide/concepts/attributes/index.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1036.md b/docs/fundamentals/code-analysis/quality-rules/ca1036.md index ffe032ba6fc9e..f2d93773ab60b 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1036.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1036.md @@ -1,7 +1,7 @@ --- title: "CA1036: Override methods on comparable types (code analysis)" description: "Learn about code analysis rule CA1036: Override methods on comparable types" -ms.date: 03/11/2019 +ms.date: 12/10/2021 ms.topic: reference f1_keywords: - CA1036 @@ -78,4 +78,4 @@ The following application code tests the behavior of the - -- [Equality operators](../../../standard/design-guidelines/equality-operators.md) +- [Equality operators (C# reference)](../../../csharp/language-reference/operators/equality-operators.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1046.md b/docs/fundamentals/code-analysis/quality-rules/ca1046.md index ee138693f6161..ab8006b716928 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1046.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1046.md @@ -1,7 +1,7 @@ --- title: "CA1046: Do not overload operator equals on reference types (code analysis)" description: "Learn about code analysis rule CA1046: Do not overload operator equals on reference types" -ms.date: 11/04/2016 +ms.date: 12/10/2021 ms.topic: reference f1_keywords: - "DoNotOverloadOperatorEqualsOnReferenceTypes" @@ -72,4 +72,4 @@ c and a are == ? Yes ## See also - -- [Equality Operators](../../../standard/design-guidelines/equality-operators.md) +- [Equality operators (C# reference)](../../../csharp/language-reference/operators/equality-operators.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1710.md b/docs/fundamentals/code-analysis/quality-rules/ca1710.md index 1c43dab665555..1efac0b90c2b4 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1710.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1710.md @@ -1,7 +1,7 @@ --- title: "CA1710: Identifiers should have correct suffix (code analysis)" description: "Learn about code analysis rule CA1710: Identifiers should have correct suffix" -ms.date: 06/11/2020 +ms.date: 12/10/2021 ms.topic: reference f1_keywords: - CA1710 @@ -131,5 +131,5 @@ Examples: ## See also -- [Attributes](../../../standard/design-guidelines/attributes.md) +- [Attributes (C#)](../../../csharp/programming-guide/concepts/attributes/index.md) - [Handling and raising events](../../../standard/events/index.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1711.md b/docs/fundamentals/code-analysis/quality-rules/ca1711.md index 228e82bd4dc29..73d649d30169e 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1711.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1711.md @@ -1,7 +1,7 @@ --- title: "CA1711: Identifiers should not have incorrect suffix (code analysis)" description: "Learn about code analysis rule CA1711: Identifiers should not have incorrect suffix" -ms.date: 07/21/2020 +ms.date: 12/10/2021 ms.topic: reference f1_keywords: - CA1711 @@ -57,7 +57,7 @@ In addition, the following suffixes should **not** be used: - `Flag` or `Flags` for enum types -Naming conventions provide a common look for libraries that target the common language runtime. This reduces the learning curve that is required for new software libraries, and increases customer confidence that the library was developed by someone who has expertise in developing managed code. For more information, see [Naming guidelines: Classes, Structs, and Interfaces](../../../standard/design-guidelines/names-of-classes-structs-and-interfaces.md). +Naming conventions provide a common look for libraries that target the common language runtime. This reduces the learning curve that is required for new software libraries, and increases customer confidence that the library was developed by someone who has expertise in developing managed code. For more information, see [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines). ## How to fix violations @@ -92,6 +92,6 @@ dotnet_code_quality.ca1711.allowed_suffixes = Flag|Flags ## See also -- [Attributes](../../../standard/design-guidelines/attributes.md) +- [Attributes (C#)](../../../csharp/programming-guide/concepts/attributes/index.md) - [Handling and raising events](../../../standard/events/index.md) -- [Naming guidelines: Classes, Structs, and Interfaces](../../../standard/design-guidelines/names-of-classes-structs-and-interfaces.md) +- [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1714.md b/docs/fundamentals/code-analysis/quality-rules/ca1714.md index 15bc8dd8f04e9..f433697fb23f2 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1714.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1714.md @@ -1,7 +1,7 @@ --- title: "CA1714: Flags enums should have plural names (code analysis)" description: "Learn about code analysis rule CA1714: Flags enums should have plural names" -ms.date: 03/11/2019 +ms.date: 12/10/2021 ms.topic: reference f1_keywords: - FlagsEnumsShouldHavePluralNames @@ -58,4 +58,4 @@ You can configure this option for just this rule, for all rules, or for all rule ## See also - -- [Enum design](../../../standard/design-guidelines/enum.md) +- [Enumeration types (C# reference)](../../../csharp/language-reference/builtin-types/enum.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1717.md b/docs/fundamentals/code-analysis/quality-rules/ca1717.md index 0c5274d73aa42..aa99297cf3f2c 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1717.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1717.md @@ -1,7 +1,7 @@ --- title: "CA1717: Only FlagsAttribute enums should have plural names (code analysis)" description: "Learn about code analysis rule CA1717: Only FlagsAttribute enums should have plural names" -ms.date: 03/11/2019 +ms.date: 12/10/2021 ms.topic: reference f1_keywords: - CA1717 @@ -61,4 +61,4 @@ You can configure this option for just this rule, for all rules, or for all rule ## See also - -- [Enum design](../../../standard/design-guidelines/enum.md) +- [Enumeration types (C# reference)](../../../csharp/language-reference/builtin-types/enum.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1813.md b/docs/fundamentals/code-analysis/quality-rules/ca1813.md index 6fd984f7b9810..d4e5810f26d01 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1813.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1813.md @@ -54,4 +54,4 @@ The following example shows a custom attribute that satisfies this rule. ## See also -- [Attributes](../../../standard/design-guidelines/attributes.md) +- [Attributes (C#)](../../../csharp/programming-guide/concepts/attributes/index.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2218.md b/docs/fundamentals/code-analysis/quality-rules/ca2218.md index bc6e5c3899c59..448c3a71a05ad 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2218.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2218.md @@ -1,7 +1,7 @@ --- title: "CA2218: Override GetHashCode on overriding Equals" description: "Learn about code analysis rule CA2218: Override GetHashCode on overriding Equals" -ms.date: 11/04/2016 +ms.date: 12/10/2021 ms.topic: reference f1_keywords: - CA2218 @@ -73,4 +73,4 @@ The following example fixes the violation by overriding - - -- [Equality Operators](../../../standard/design-guidelines/equality-operators.md) +- [Equality operators (C# reference)](../../../csharp/language-reference/operators/equality-operators.md) diff --git a/docs/fundamentals/code-analysis/quality-rules/design-warnings.md b/docs/fundamentals/code-analysis/quality-rules/design-warnings.md index 8ced4a29769da..98c613b2d4663 100644 --- a/docs/fundamentals/code-analysis/quality-rules/design-warnings.md +++ b/docs/fundamentals/code-analysis/quality-rules/design-warnings.md @@ -1,7 +1,7 @@ --- title: Design rules (code analysis) description: "Learn about code analysis design rules." -ms.date: 11/04/2016 +ms.date: 12/10/2021 ms.topic: reference f1_keywords: - vs.codeanalysis.designrules @@ -14,7 +14,7 @@ ms.author: gewarren --- # Design rules -Design rules support adherence to the [.NET Framework design guidelines](../../../standard/design-guidelines/index.md). +Design rules support adherence to the [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines). ## In this section diff --git a/docs/fundamentals/code-analysis/quality-rules/naming-warnings.md b/docs/fundamentals/code-analysis/quality-rules/naming-warnings.md index a629b3db41206..c4cafc4ba4740 100644 --- a/docs/fundamentals/code-analysis/quality-rules/naming-warnings.md +++ b/docs/fundamentals/code-analysis/quality-rules/naming-warnings.md @@ -1,7 +1,7 @@ --- title: Naming rules (code analysis) description: "Learn about code analysis naming rules." -ms.date: 11/04/2016 +ms.date: 12/10/2021 ms.topic: reference f1_keywords: - vs.codeanalysis.namingrules @@ -14,24 +14,24 @@ ms.author: gewarren --- # Naming rules -Naming rules support adherence to the [naming conventions of the .NET design guidelines](../../../standard/design-guidelines/naming-guidelines.md). +Naming rules support adherence to the [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines). ## In this section -|Rule|Description| -|----------|-----------------| -|[CA1700: Do not name enum values 'Reserved'](ca1700.md)|This rule assumes that an enumeration member that has a name that contains "reserved" is not currently used but is a placeholder to be renamed or removed in a future version. Renaming or removing a member is a breaking change.| -|[CA1707: Identifiers should not contain underscores](ca1707.md)|By convention, identifier names do not contain the underscore (_) character. This rule checks namespaces, types, members, and parameters.| -|[CA1708: Identifiers should differ by more than case](ca1708.md)|Identifiers for namespaces, types, members, and parameters cannot differ only by case because languages that target the common language runtime are not required to be case-sensitive.| -|[CA1710: Identifiers should have correct suffix](ca1710.md)|By convention, the names of types that extend certain base types or that implement certain interfaces, or types derived from these types, have a suffix that is associated with the base type or interface.| -|[CA1711: Identifiers should not have incorrect suffix](ca1711.md)|By convention, only the names of types that extend certain base types or that implement certain interfaces, or types that are derived from these types, should end with specific reserved suffixes. Other type names should not use these reserved suffixes.| -|[CA1712: Do not prefix enum values with type name](ca1712.md)|Names of enumeration members are not prefixed with the type name because type information is expected to be provided by development tools.| -|[CA1713: Events should not have before or after prefix](ca1713.md)|The name of an event starts with "Before" or "After". To name related events that are raised in a specific sequence, use the present or past tense to indicate the relative position in the sequence of actions.| -|[CA1714: Flags enums should have plural names](ca1714.md)|A public enumeration has the System.FlagsAttribute attribute and its name does not end in "s". Types that are marked with FlagsAttribute have names that are plural because the attribute indicates that more than one value can be specified.| -|[CA1715: Identifiers should have correct prefix](ca1715.md)|The name of an externally visible interface does not start with a capital "I". The name of a generic type parameter on an externally visible type or method does not start with a capital "T".| -|[CA1716: Identifiers should not match keywords](ca1716.md)|A namespace name or a type name matches a reserved keyword in a programming language. Identifiers for namespaces and types should not match keywords that are defined by languages that target the common language runtime.| -|[CA1717: Only FlagsAttribute enums should have plural names](ca1717.md)|Naming conventions dictate that a plural name for an enumeration indicates that more than one value of the enumeration can be specified at the same time.| -|[CA1720: Identifiers should not contain type names](ca1720.md)|The name of a parameter in an externally visible member contains a data type name, or the name of an externally visible member contains a language-specific data type name.| -|[CA1721: Property names should not match get methods](ca1721.md)|The name of a public or protected member starts with "Get" and otherwise matches the name of a public or protected property. "Get" methods and properties should have names that clearly distinguish their function.| -|[CA1724: Type Names Should Not Match Namespaces](ca1724.md)|Type names should not match the names of .NET namespaces. Violation of this rule can reduce the usability of the library.| -|[CA1725: Parameter names should match base declaration](ca1725.md)|Consistent naming of parameters in an override hierarchy increases the usability of the method overrides. A parameter name in a derived method that differs from the name in the base declaration can cause confusion about whether the method is an override of the base method or a new overload of the method.| +| Rule | Description | +|--|--| +| [CA1700: Do not name enum values 'Reserved'](ca1700.md) | This rule assumes that an enumeration member that has a name that contains "reserved" is not currently used but is a placeholder to be renamed or removed in a future version. Renaming or removing a member is a breaking change. | +| [CA1707: Identifiers should not contain underscores](ca1707.md) | By convention, identifier names do not contain the underscore (_) character. This rule checks namespaces, types, members, and parameters. | +| [CA1708: Identifiers should differ by more than case](ca1708.md) | Identifiers for namespaces, types, members, and parameters cannot differ only by case because languages that target the common language runtime are not required to be case-sensitive. | +| [CA1710: Identifiers should have correct suffix](ca1710.md) | By convention, the names of types that extend certain base types or that implement certain interfaces, or types derived from these types, have a suffix that is associated with the base type or interface. | +| [CA1711: Identifiers should not have incorrect suffix](ca1711.md) | By convention, only the names of types that extend certain base types or that implement certain interfaces, or types that are derived from these types, should end with specific reserved suffixes. Other type names should not use these reserved suffixes. | +| [CA1712: Do not prefix enum values with type name](ca1712.md) | Names of enumeration members are not prefixed with the type name because type information is expected to be provided by development tools. | +| [CA1713: Events should not have before or after prefix](ca1713.md) | The name of an event starts with "Before" or "After". To name related events that are raised in a specific sequence, use the present or past tense to indicate the relative position in the sequence of actions. | +| [CA1714: Flags enums should have plural names](ca1714.md) | A public enumeration has the System.FlagsAttribute attribute and its name does not end in "s". Types that are marked with FlagsAttribute have names that are plural because the attribute indicates that more than one value can be specified. | +| [CA1715: Identifiers should have correct prefix](ca1715.md) | The name of an externally visible interface does not start with a capital "I". The name of a generic type parameter on an externally visible type or method does not start with a capital "T". | +| [CA1716: Identifiers should not match keywords](ca1716.md) | A namespace name or a type name matches a reserved keyword in a programming language. Identifiers for namespaces and types should not match keywords that are defined by languages that target the common language runtime. | +| [CA1717: Only FlagsAttribute enums should have plural names](ca1717.md) | Naming conventions dictate that a plural name for an enumeration indicates that more than one value of the enumeration can be specified at the same time. | +| [CA1720: Identifiers should not contain type names](ca1720.md) | The name of a parameter in an externally visible member contains a data type name, or the name of an externally visible member contains a language-specific data type name. | +| [CA1721: Property names should not match get methods](ca1721.md) | The name of a public or protected member starts with "Get" and otherwise matches the name of a public or protected property. "Get" methods and properties should have names that clearly distinguish their function. | +| [CA1724: Type Names Should Not Match Namespaces](ca1724.md) | Type names should not match the names of .NET namespaces. Violation of this rule can reduce the usability of the library. | +| [CA1725: Parameter names should match base declaration](ca1725.md) | Consistent naming of parameters in an override hierarchy increases the usability of the method overrides. A parameter name in a derived method that differs from the name in the base declaration can cause confusion about whether the method is an override of the base method or a new overload of the method. | diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index 1faee85b8efdf..7f785e3fc4ac2 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -74,69 +74,69 @@ items: - name: Use Visual Studio items: - name: Create a console app - href: ../core/tutorials/with-visual-studio.md displayName: tutorials, visual studio, vs + href: ../core/tutorials/with-visual-studio.md - name: Debug an app - href: ../core/tutorials/debugging-with-visual-studio.md displayName: tutorials, visual studio, vs + href: ../core/tutorials/debugging-with-visual-studio.md - name: Publish an app - href: ../core/tutorials/publishing-with-visual-studio.md displayName: tutorials, visual studio, vs + href: ../core/tutorials/publishing-with-visual-studio.md - name: Create a library - href: ../core/tutorials/library-with-visual-studio.md displayName: tutorials, visual studio, vs + href: ../core/tutorials/library-with-visual-studio.md - name: Unit test a library - href: ../core/tutorials/testing-library-with-visual-studio.md displayName: tutorials, visual studio, vs + href: ../core/tutorials/testing-library-with-visual-studio.md - name: Install and use a package - href: /nuget/quickstart/install-and-use-a-package-in-visual-studio displayName: tutorials, visual studio, vs + href: /nuget/quickstart/install-and-use-a-package-in-visual-studio - name: Create and publish a package - href: /nuget/quickstart/create-and-publish-a-package-using-visual-studio displayName: tutorials, visual studio, vs + href: /nuget/quickstart/create-and-publish-a-package-using-visual-studio - name: Use Visual Studio Code items: - name: Create a console app - href: ../core/tutorials/with-visual-studio-code.md displayName: tutorials, visual studio code, vs code, cli + href: ../core/tutorials/with-visual-studio-code.md - name: Debug an app - href: ../core/tutorials/debugging-with-visual-studio-code.md displayName: tutorials, visual studio code, vs code + href: ../core/tutorials/debugging-with-visual-studio-code.md - name: Publish an app - href: ../core/tutorials/publishing-with-visual-studio-code.md displayName: tutorials, visual studio code, vs code + href: ../core/tutorials/publishing-with-visual-studio-code.md - name: Create a library - href: ../core/tutorials/library-with-visual-studio-code.md displayName: tutorials, visual studio code, vs code + href: ../core/tutorials/library-with-visual-studio-code.md - name: Unit test a library - href: ../core/tutorials/testing-library-with-visual-studio-code.md displayName: tutorials, visual studio code, vs code + href: ../core/tutorials/testing-library-with-visual-studio-code.md - name: Install and use a package - href: /nuget/quickstart/install-and-use-a-package-using-the-dotnet-cli displayName: tutorials, cli + href: /nuget/quickstart/install-and-use-a-package-using-the-dotnet-cli - name: Create and publish a package - href: /nuget/quickstart/create-and-publish-a-package-using-the-dotnet-cli displayName: tutorials + href: /nuget/quickstart/create-and-publish-a-package-using-the-dotnet-cli - name: Use Visual Studio for Mac items: - name: Create a console app - href: ../core/tutorials/with-visual-studio-mac.md displayName: tutorials, visual studio for mac, vs for mac, cli + href: ../core/tutorials/with-visual-studio-mac.md - name: Debug an app - href: ../core/tutorials/debugging-with-visual-studio-mac.md displayName: tutorials, visual studio for mac, vs for mac + href: ../core/tutorials/debugging-with-visual-studio-mac.md - name: Publish an app - href: ../core/tutorials/publishing-with-visual-studio-mac.md displayName: tutorials, visual studio for mac, vs for mac + href: ../core/tutorials/publishing-with-visual-studio-mac.md - name: Create a library - href: ../core/tutorials/library-with-visual-studio-mac.md displayName: tutorials, visual studio for mac, vs for mac + href: ../core/tutorials/library-with-visual-studio-mac.md - name: Unit test a library - href: ../core/tutorials/testing-library-with-visual-studio-mac.md displayName: tutorials, visual studio for mac, vs for mac + href: ../core/tutorials/testing-library-with-visual-studio-mac.md - name: Install and use a package - href: /nuget/quickstart/install-and-use-a-package-in-visual-studio-mac displayName: tutorials, visual studio for mac, vs for mac + href: /nuget/quickstart/install-and-use-a-package-in-visual-studio-mac - name: More tutorials href: ../core/tutorials/index.md - name: What's new in .NET @@ -185,7 +185,7 @@ items: - name: .NET SDK items: - name: Overview - displayName: '.net sdk,software development kit,software dev kit,tool' + displayName: .net sdk,software development kit,software dev kit,tool href: ../core/sdk.md - name: Environment variables href: ../core/tools/dotnet-environment-variables.md @@ -234,7 +234,7 @@ items: - name: .NET CLI items: - name: Overview - displayName: '.net cli,command-line interface,cli,tool' + displayName: .net cli,command-line interface,cli,tool href: ../core/tools/index.md - name: dotnet href: ../core/tools/dotnet.md @@ -373,14 +373,14 @@ items: - name: Create templates for the CLI items: - name: 1 - Create an item template - href: ../core/tutorials/cli-templates-create-item-template.md displayName: tutorials, cli + href: ../core/tutorials/cli-templates-create-item-template.md - name: 2 - Create a project template - href: ../core/tutorials/cli-templates-create-project-template.md displayName: tutorials, cli + href: ../core/tutorials/cli-templates-create-project-template.md - name: 3 - Create a template package - href: ../core/tutorials/cli-templates-create-template-package.md displayName: tutorials, cli + href: ../core/tutorials/cli-templates-create-template-package.md - name: SYSLIB diagnostics items: - name: Obsoletions @@ -556,8 +556,8 @@ items: displayName: tools,tutorials,cli,understand global tool href: ../core/tools/global-tools-how-to-use.md - name: 3 - Use a local tool - href: ../core/tools/local-tools-how-to-use.md displayName: tools,tutorials,cli,local tool + href: ../core/tools/local-tools-how-to-use.md - name: Additional tools items: - name: Overview @@ -629,7 +629,7 @@ items: href: ../core/diagnostics/event-counters.md - name: Well-known counters href: ../core/diagnostics/available-counters.md - - name: "Tutorial: Measure performance with EventCounters" + - name: 'Tutorial: Measure performance with EventCounters' href: ../core/diagnostics/event-counter-perf.md - name: Compare metric APIs href: ../core/diagnostics/compare-metric-apis.md @@ -699,8 +699,8 @@ items: - name: Code analysis items: - name: Overview - href: code-analysis/overview.md displayName: code analysis, analyzers + href: code-analysis/overview.md - name: Configuration items: - name: General options @@ -730,7 +730,7 @@ items: - name: Design rules items: - name: Overview - displayName: "design rules" + displayName: design rules href: code-analysis/quality-rules/design-warnings.md - name: CA1000 href: code-analysis/quality-rules/ca1000.md @@ -833,14 +833,14 @@ items: - name: Documentation rules items: - name: Overview - displayName: "documentation rules" + displayName: documentation rules href: code-analysis/quality-rules/documentation-warnings.md - name: CA1200 href: code-analysis/quality-rules/ca1200.md - name: Globalization rules items: - name: Overview - displayName: "globalization rules" + displayName: globalization rules href: code-analysis/quality-rules/globalization-warnings.md - name: CA1303 href: code-analysis/quality-rules/ca1303.md @@ -861,7 +861,7 @@ items: - name: Portability and interoperability rules items: - name: Overview - displayName: "portability and interoperability rules" + displayName: portability and interoperability rules href: code-analysis/quality-rules/interoperability-warnings.md - name: CA1401 href: code-analysis/quality-rules/ca1401.md @@ -874,7 +874,7 @@ items: - name: Maintainability rules items: - name: Overview - displayName: "maintainability rules" + displayName: maintainability rules href: code-analysis/quality-rules/maintainability-warnings.md - name: CA1501 href: code-analysis/quality-rules/ca1501.md @@ -893,7 +893,7 @@ items: - name: Naming rules items: - name: Overview - displayName: "naming rules" + displayName: naming rules href: code-analysis/quality-rules/naming-warnings.md - name: CA1700 href: code-analysis/quality-rules/ca1700.md @@ -928,7 +928,7 @@ items: - name: Performance rules items: - name: Overview - displayName: "performance rules" + displayName: performance rules href: code-analysis/quality-rules/performance-warnings.md - name: CA1802 href: code-analysis/quality-rules/ca1802.md @@ -1007,7 +1007,7 @@ items: - name: SingleFile rules items: - name: Overview - displayName: "singlefile rules" + displayName: singlefile rules href: code-analysis/quality-rules/singlefile-warnings.md - name: IL3000 href: code-analysis/quality-rules/il3000.md @@ -1018,7 +1018,7 @@ items: - name: Reliability rules items: - name: Overview - displayName: "reliability rules" + displayName: reliability rules href: code-analysis/quality-rules/reliability-warnings.md - name: CA2000 href: code-analysis/quality-rules/ca2000.md @@ -1047,7 +1047,7 @@ items: - name: Security rules items: - name: Overview - displayName: "security rules" + displayName: security rules href: code-analysis/quality-rules/security-warnings.md - name: CA2100 href: code-analysis/quality-rules/ca2100.md @@ -1242,7 +1242,7 @@ items: - name: Usage rules items: - name: Overview - displayName: "usage rules" + displayName: usage rules href: code-analysis/quality-rules/usage-warnings.md - name: CA1801 href: code-analysis/quality-rules/ca1801.md @@ -1323,7 +1323,7 @@ items: - name: Language rules items: - name: Overview - displayName: "language rules" + displayName: language rules href: code-analysis/style-rules/language-rules.md - name: this and Me preferences items: @@ -1633,222 +1633,222 @@ items: href: ../core/deploying/trimming/prepare-libraries-for-trimming.md - name: Trim warnings items: - - name: IL2001 - href: ../core/deploying/trimming/trim-warnings/il2001.md - - name: IL2002 - href: ../core/deploying/trimming/trim-warnings/il2002.md - - name: IL2003 - href: ../core/deploying/trimming/trim-warnings/il2003.md - - name: IL2004 - href: ../core/deploying/trimming/trim-warnings/il2004.md - - name: IL2005 - href: ../core/deploying/trimming/trim-warnings/il2005.md - - name: IL2007 - href: ../core/deploying/trimming/trim-warnings/il2007.md - - name: IL2008 - href: ../core/deploying/trimming/trim-warnings/il2008.md - - name: IL2009 - href: ../core/deploying/trimming/trim-warnings/il2009.md - - name: IL2010 - href: ../core/deploying/trimming/trim-warnings/il2010.md - - name: IL2011 - href: ../core/deploying/trimming/trim-warnings/il2011.md - - name: IL2012 - href: ../core/deploying/trimming/trim-warnings/il2012.md - - name: IL2013 - href: ../core/deploying/trimming/trim-warnings/il2013.md - - name: IL2014 - href: ../core/deploying/trimming/trim-warnings/il2014.md - - name: IL2015 - href: ../core/deploying/trimming/trim-warnings/il2015.md - - name: IL2016 - href: ../core/deploying/trimming/trim-warnings/il2016.md - - name: IL2017 - href: ../core/deploying/trimming/trim-warnings/il2017.md - - name: IL2018 - href: ../core/deploying/trimming/trim-warnings/il2018.md - - name: IL2019 - href: ../core/deploying/trimming/trim-warnings/il2019.md - - name: IL2022 - href: ../core/deploying/trimming/trim-warnings/il2022.md - - name: IL2023 - href: ../core/deploying/trimming/trim-warnings/il2023.md - - name: IL2024 - href: ../core/deploying/trimming/trim-warnings/il2024.md - - name: IL2025 - href: ../core/deploying/trimming/trim-warnings/il2025.md - - name: IL2026 - href: ../core/deploying/trimming/trim-warnings/il2026.md - - name: IL2027 - href: ../core/deploying/trimming/trim-warnings/il2027.md - - name: IL2028 - href: ../core/deploying/trimming/trim-warnings/il2028.md - - name: IL2029 - href: ../core/deploying/trimming/trim-warnings/il2029.md - - name: IL2030 - href: ../core/deploying/trimming/trim-warnings/il2030.md - - name: IL2031 - href: ../core/deploying/trimming/trim-warnings/il2031.md - - name: IL2032 - href: ../core/deploying/trimming/trim-warnings/il2032.md - - name: IL2033 - href: ../core/deploying/trimming/trim-warnings/il2033.md - - name: IL2034 - href: ../core/deploying/trimming/trim-warnings/il2034.md - - name: IL2035 - href: ../core/deploying/trimming/trim-warnings/il2035.md - - name: IL2036 - href: ../core/deploying/trimming/trim-warnings/il2036.md - - name: IL2037 - href: ../core/deploying/trimming/trim-warnings/il2037.md - - name: IL2038 - href: ../core/deploying/trimming/trim-warnings/il2038.md - - name: IL2039 - href: ../core/deploying/trimming/trim-warnings/il2039.md - - name: IL2040 - href: ../core/deploying/trimming/trim-warnings/il2040.md - - name: IL2041 - href: ../core/deploying/trimming/trim-warnings/il2041.md - - name: IL2042 - href: ../core/deploying/trimming/trim-warnings/il2042.md - - name: IL2043 - href: ../core/deploying/trimming/trim-warnings/il2043.md - - name: IL2044 - href: ../core/deploying/trimming/trim-warnings/il2044.md - - name: IL2045 - href: ../core/deploying/trimming/trim-warnings/il2045.md - - name: IL2046 - href: ../core/deploying/trimming/trim-warnings/il2046.md - - name: IL2048 - href: ../core/deploying/trimming/trim-warnings/il2048.md - - name: IL2049 - href: ../core/deploying/trimming/trim-warnings/il2049.md - - name: IL2050 - href: ../core/deploying/trimming/trim-warnings/il2050.md - - name: IL2051 - href: ../core/deploying/trimming/trim-warnings/il2051.md - - name: IL2052 - href: ../core/deploying/trimming/trim-warnings/il2052.md - - name: IL2053 - href: ../core/deploying/trimming/trim-warnings/il2053.md - - name: IL2054 - href: ../core/deploying/trimming/trim-warnings/il2054.md - - name: IL2055 - href: ../core/deploying/trimming/trim-warnings/il2055.md - - name: IL2056 - href: ../core/deploying/trimming/trim-warnings/il2056.md - - name: IL2057 - href: ../core/deploying/trimming/trim-warnings/il2057.md - - name: IL2058 - href: ../core/deploying/trimming/trim-warnings/il2058.md - - name: IL2059 - href: ../core/deploying/trimming/trim-warnings/il2059.md - - name: IL2060 - href: ../core/deploying/trimming/trim-warnings/il2060.md - - name: IL2061 - href: ../core/deploying/trimming/trim-warnings/il2061.md - - name: IL2062 - href: ../core/deploying/trimming/trim-warnings/il2062.md - - name: IL2063 - href: ../core/deploying/trimming/trim-warnings/il2063.md - - name: IL2064 - href: ../core/deploying/trimming/trim-warnings/il2064.md - - name: IL2065 - href: ../core/deploying/trimming/trim-warnings/il2065.md - - name: IL2066 - href: ../core/deploying/trimming/trim-warnings/il2066.md - - name: IL2067 - href: ../core/deploying/trimming/trim-warnings/il2067.md - - name: IL2068 - href: ../core/deploying/trimming/trim-warnings/il2068.md - - name: IL2069 - href: ../core/deploying/trimming/trim-warnings/il2069.md - - name: IL2070 - href: ../core/deploying/trimming/trim-warnings/il2070.md - - name: IL2072 - href: ../core/deploying/trimming/trim-warnings/il2072.md - - name: IL2073 - href: ../core/deploying/trimming/trim-warnings/il2073.md - - name: IL2074 - href: ../core/deploying/trimming/trim-warnings/il2074.md - - name: IL2075 - href: ../core/deploying/trimming/trim-warnings/il2075.md - - name: IL2077 - href: ../core/deploying/trimming/trim-warnings/il2077.md - - name: IL2078 - href: ../core/deploying/trimming/trim-warnings/il2078.md - - name: IL2079 - href: ../core/deploying/trimming/trim-warnings/il2079.md - - name: IL2080 - href: ../core/deploying/trimming/trim-warnings/il2080.md - - name: IL2082 - href: ../core/deploying/trimming/trim-warnings/il2082.md - - name: IL2083 - href: ../core/deploying/trimming/trim-warnings/il2083.md - - name: IL2084 - href: ../core/deploying/trimming/trim-warnings/il2084.md - - name: IL2085 - href: ../core/deploying/trimming/trim-warnings/il2085.md - - name: IL2087 - href: ../core/deploying/trimming/trim-warnings/il2087.md - - name: IL2088 - href: ../core/deploying/trimming/trim-warnings/il2088.md - - name: IL2089 - href: ../core/deploying/trimming/trim-warnings/il2089.md - - name: IL2090 - href: ../core/deploying/trimming/trim-warnings/il2090.md - - name: IL2091 - href: ../core/deploying/trimming/trim-warnings/il2091.md - - name: IL2092 - href: ../core/deploying/trimming/trim-warnings/il2092.md - - name: IL2093 - href: ../core/deploying/trimming/trim-warnings/il2093.md - - name: IL2094 - href: ../core/deploying/trimming/trim-warnings/il2094.md - - name: IL2095 - href: ../core/deploying/trimming/trim-warnings/il2095.md - - name: IL2096 - href: ../core/deploying/trimming/trim-warnings/il2096.md - - name: IL2097 - href: ../core/deploying/trimming/trim-warnings/il2097.md - - name: IL2098 - href: ../core/deploying/trimming/trim-warnings/il2098.md - - name: IL2099 - href: ../core/deploying/trimming/trim-warnings/il2099.md - - name: IL2100 - href: ../core/deploying/trimming/trim-warnings/il2100.md - - name: IL2101 - href: ../core/deploying/trimming/trim-warnings/il2101.md - - name: IL2102 - href: ../core/deploying/trimming/trim-warnings/il2102.md - - name: IL2103 - href: ../core/deploying/trimming/trim-warnings/il2103.md - - name: IL2104 - href: ../core/deploying/trimming/trim-warnings/il2104.md - - name: IL2105 - href: ../core/deploying/trimming/trim-warnings/il2105.md - - name: IL2106 - href: ../core/deploying/trimming/trim-warnings/il2106.md - - name: IL2107 - href: ../core/deploying/trimming/trim-warnings/il2107.md - - name: IL2108 - href: ../core/deploying/trimming/trim-warnings/il2108.md - - name: IL2109 - href: ../core/deploying/trimming/trim-warnings/il2109.md - - name: IL2110 - href: ../core/deploying/trimming/trim-warnings/il2110.md - - name: IL2111 - href: ../core/deploying/trimming/trim-warnings/il2111.md - - name: IL2112 - href: ../core/deploying/trimming/trim-warnings/il2112.md - - name: IL2113 - href: ../core/deploying/trimming/trim-warnings/il2113.md - - name: IL2114 - href: ../core/deploying/trimming/trim-warnings/il2114.md - - name: IL2115 - href: ../core/deploying/trimming/trim-warnings/il2115.md - - name: IL2116 - href: ../core/deploying/trimming/trim-warnings/il2116.md + - name: IL2001 + href: ../core/deploying/trimming/trim-warnings/il2001.md + - name: IL2002 + href: ../core/deploying/trimming/trim-warnings/il2002.md + - name: IL2003 + href: ../core/deploying/trimming/trim-warnings/il2003.md + - name: IL2004 + href: ../core/deploying/trimming/trim-warnings/il2004.md + - name: IL2005 + href: ../core/deploying/trimming/trim-warnings/il2005.md + - name: IL2007 + href: ../core/deploying/trimming/trim-warnings/il2007.md + - name: IL2008 + href: ../core/deploying/trimming/trim-warnings/il2008.md + - name: IL2009 + href: ../core/deploying/trimming/trim-warnings/il2009.md + - name: IL2010 + href: ../core/deploying/trimming/trim-warnings/il2010.md + - name: IL2011 + href: ../core/deploying/trimming/trim-warnings/il2011.md + - name: IL2012 + href: ../core/deploying/trimming/trim-warnings/il2012.md + - name: IL2013 + href: ../core/deploying/trimming/trim-warnings/il2013.md + - name: IL2014 + href: ../core/deploying/trimming/trim-warnings/il2014.md + - name: IL2015 + href: ../core/deploying/trimming/trim-warnings/il2015.md + - name: IL2016 + href: ../core/deploying/trimming/trim-warnings/il2016.md + - name: IL2017 + href: ../core/deploying/trimming/trim-warnings/il2017.md + - name: IL2018 + href: ../core/deploying/trimming/trim-warnings/il2018.md + - name: IL2019 + href: ../core/deploying/trimming/trim-warnings/il2019.md + - name: IL2022 + href: ../core/deploying/trimming/trim-warnings/il2022.md + - name: IL2023 + href: ../core/deploying/trimming/trim-warnings/il2023.md + - name: IL2024 + href: ../core/deploying/trimming/trim-warnings/il2024.md + - name: IL2025 + href: ../core/deploying/trimming/trim-warnings/il2025.md + - name: IL2026 + href: ../core/deploying/trimming/trim-warnings/il2026.md + - name: IL2027 + href: ../core/deploying/trimming/trim-warnings/il2027.md + - name: IL2028 + href: ../core/deploying/trimming/trim-warnings/il2028.md + - name: IL2029 + href: ../core/deploying/trimming/trim-warnings/il2029.md + - name: IL2030 + href: ../core/deploying/trimming/trim-warnings/il2030.md + - name: IL2031 + href: ../core/deploying/trimming/trim-warnings/il2031.md + - name: IL2032 + href: ../core/deploying/trimming/trim-warnings/il2032.md + - name: IL2033 + href: ../core/deploying/trimming/trim-warnings/il2033.md + - name: IL2034 + href: ../core/deploying/trimming/trim-warnings/il2034.md + - name: IL2035 + href: ../core/deploying/trimming/trim-warnings/il2035.md + - name: IL2036 + href: ../core/deploying/trimming/trim-warnings/il2036.md + - name: IL2037 + href: ../core/deploying/trimming/trim-warnings/il2037.md + - name: IL2038 + href: ../core/deploying/trimming/trim-warnings/il2038.md + - name: IL2039 + href: ../core/deploying/trimming/trim-warnings/il2039.md + - name: IL2040 + href: ../core/deploying/trimming/trim-warnings/il2040.md + - name: IL2041 + href: ../core/deploying/trimming/trim-warnings/il2041.md + - name: IL2042 + href: ../core/deploying/trimming/trim-warnings/il2042.md + - name: IL2043 + href: ../core/deploying/trimming/trim-warnings/il2043.md + - name: IL2044 + href: ../core/deploying/trimming/trim-warnings/il2044.md + - name: IL2045 + href: ../core/deploying/trimming/trim-warnings/il2045.md + - name: IL2046 + href: ../core/deploying/trimming/trim-warnings/il2046.md + - name: IL2048 + href: ../core/deploying/trimming/trim-warnings/il2048.md + - name: IL2049 + href: ../core/deploying/trimming/trim-warnings/il2049.md + - name: IL2050 + href: ../core/deploying/trimming/trim-warnings/il2050.md + - name: IL2051 + href: ../core/deploying/trimming/trim-warnings/il2051.md + - name: IL2052 + href: ../core/deploying/trimming/trim-warnings/il2052.md + - name: IL2053 + href: ../core/deploying/trimming/trim-warnings/il2053.md + - name: IL2054 + href: ../core/deploying/trimming/trim-warnings/il2054.md + - name: IL2055 + href: ../core/deploying/trimming/trim-warnings/il2055.md + - name: IL2056 + href: ../core/deploying/trimming/trim-warnings/il2056.md + - name: IL2057 + href: ../core/deploying/trimming/trim-warnings/il2057.md + - name: IL2058 + href: ../core/deploying/trimming/trim-warnings/il2058.md + - name: IL2059 + href: ../core/deploying/trimming/trim-warnings/il2059.md + - name: IL2060 + href: ../core/deploying/trimming/trim-warnings/il2060.md + - name: IL2061 + href: ../core/deploying/trimming/trim-warnings/il2061.md + - name: IL2062 + href: ../core/deploying/trimming/trim-warnings/il2062.md + - name: IL2063 + href: ../core/deploying/trimming/trim-warnings/il2063.md + - name: IL2064 + href: ../core/deploying/trimming/trim-warnings/il2064.md + - name: IL2065 + href: ../core/deploying/trimming/trim-warnings/il2065.md + - name: IL2066 + href: ../core/deploying/trimming/trim-warnings/il2066.md + - name: IL2067 + href: ../core/deploying/trimming/trim-warnings/il2067.md + - name: IL2068 + href: ../core/deploying/trimming/trim-warnings/il2068.md + - name: IL2069 + href: ../core/deploying/trimming/trim-warnings/il2069.md + - name: IL2070 + href: ../core/deploying/trimming/trim-warnings/il2070.md + - name: IL2072 + href: ../core/deploying/trimming/trim-warnings/il2072.md + - name: IL2073 + href: ../core/deploying/trimming/trim-warnings/il2073.md + - name: IL2074 + href: ../core/deploying/trimming/trim-warnings/il2074.md + - name: IL2075 + href: ../core/deploying/trimming/trim-warnings/il2075.md + - name: IL2077 + href: ../core/deploying/trimming/trim-warnings/il2077.md + - name: IL2078 + href: ../core/deploying/trimming/trim-warnings/il2078.md + - name: IL2079 + href: ../core/deploying/trimming/trim-warnings/il2079.md + - name: IL2080 + href: ../core/deploying/trimming/trim-warnings/il2080.md + - name: IL2082 + href: ../core/deploying/trimming/trim-warnings/il2082.md + - name: IL2083 + href: ../core/deploying/trimming/trim-warnings/il2083.md + - name: IL2084 + href: ../core/deploying/trimming/trim-warnings/il2084.md + - name: IL2085 + href: ../core/deploying/trimming/trim-warnings/il2085.md + - name: IL2087 + href: ../core/deploying/trimming/trim-warnings/il2087.md + - name: IL2088 + href: ../core/deploying/trimming/trim-warnings/il2088.md + - name: IL2089 + href: ../core/deploying/trimming/trim-warnings/il2089.md + - name: IL2090 + href: ../core/deploying/trimming/trim-warnings/il2090.md + - name: IL2091 + href: ../core/deploying/trimming/trim-warnings/il2091.md + - name: IL2092 + href: ../core/deploying/trimming/trim-warnings/il2092.md + - name: IL2093 + href: ../core/deploying/trimming/trim-warnings/il2093.md + - name: IL2094 + href: ../core/deploying/trimming/trim-warnings/il2094.md + - name: IL2095 + href: ../core/deploying/trimming/trim-warnings/il2095.md + - name: IL2096 + href: ../core/deploying/trimming/trim-warnings/il2096.md + - name: IL2097 + href: ../core/deploying/trimming/trim-warnings/il2097.md + - name: IL2098 + href: ../core/deploying/trimming/trim-warnings/il2098.md + - name: IL2099 + href: ../core/deploying/trimming/trim-warnings/il2099.md + - name: IL2100 + href: ../core/deploying/trimming/trim-warnings/il2100.md + - name: IL2101 + href: ../core/deploying/trimming/trim-warnings/il2101.md + - name: IL2102 + href: ../core/deploying/trimming/trim-warnings/il2102.md + - name: IL2103 + href: ../core/deploying/trimming/trim-warnings/il2103.md + - name: IL2104 + href: ../core/deploying/trimming/trim-warnings/il2104.md + - name: IL2105 + href: ../core/deploying/trimming/trim-warnings/il2105.md + - name: IL2106 + href: ../core/deploying/trimming/trim-warnings/il2106.md + - name: IL2107 + href: ../core/deploying/trimming/trim-warnings/il2107.md + - name: IL2108 + href: ../core/deploying/trimming/trim-warnings/il2108.md + - name: IL2109 + href: ../core/deploying/trimming/trim-warnings/il2109.md + - name: IL2110 + href: ../core/deploying/trimming/trim-warnings/il2110.md + - name: IL2111 + href: ../core/deploying/trimming/trim-warnings/il2111.md + - name: IL2112 + href: ../core/deploying/trimming/trim-warnings/il2112.md + - name: IL2113 + href: ../core/deploying/trimming/trim-warnings/il2113.md + - name: IL2114 + href: ../core/deploying/trimming/trim-warnings/il2114.md + - name: IL2115 + href: ../core/deploying/trimming/trim-warnings/il2115.md + - name: IL2116 + href: ../core/deploying/trimming/trim-warnings/il2116.md - name: Runtime package store href: ../core/deploying/runtime-store.md - name: Runtime Identifier (RID) catalog @@ -1866,31 +1866,31 @@ items: - name: DevOps items: - name: GitHub Actions and .NET + displayName: continuous integration,continuous deployment,continuous delivery,ci,cd,ci/cd,github,github action,github actions,lifecycle href: ../devops/github-actions-overview.md - displayName: "continuous integration,continuous deployment,continuous delivery,ci,cd,ci/cd,github,github action,github actions,lifecycle" - name: Official .NET GitHub Actions href: ../devops/dotnet-github-action-reference.md - name: Tutorials - expanded: true items: - name: Create a GitHub Action with .NET + displayName: continuous integration, continuous deployment, ci, cd, ci/cd, github, github action, github actions, lifecycle href: ../devops/create-dotnet-github-action.md - displayName: "continuous integration, continuous deployment, ci, cd, ci/cd, github, github action, github actions, lifecycle" - - name: Quickstarts expanded: true + - name: Quickstarts items: - name: Create a build GitHub Action - href: ../devops/dotnet-build-github-action.md displayName: dotnet restore,dotnet build + href: ../devops/dotnet-build-github-action.md - name: Create a test GitHub Action - href: ../devops/dotnet-test-github-action.md displayName: dotnet restore,dotnet build,dotnet test + href: ../devops/dotnet-test-github-action.md - name: Create a publish GitHub Action - href: ../devops/dotnet-publish-github-action.md displayName: dotnet restore,dotnet build,dotnet test,dotnet publish + href: ../devops/dotnet-publish-github-action.md - name: Create a CodeQL GitHub Action - href: ../devops/dotnet-secure-github-action.md displayName: codeql,security,vulnerability,source scan + href: ../devops/dotnet-secure-github-action.md + expanded: true - name: Fundamental coding components items: - name: Base types overview @@ -1928,8 +1928,8 @@ items: - name: Collections and data structures items: - name: Overview - href: ../standard/collections/index.md displayName: collections, data structures + href: ../standard/collections/index.md - name: Select a collection class href: ../standard/collections/selecting-a-collection-class.md - name: Commonly used collection types @@ -1949,8 +1949,8 @@ items: - name: Events items: - name: Overview - href: ../standard/events/index.md displayName: events + href: ../standard/events/index.md - name: Raise and consume events href: ../standard/events/how-to-raise-and-consume-events.md - name: Handle multiple events using event properties @@ -1958,19 +1958,19 @@ items: - name: Observer design pattern items: - name: Overview - href: ../standard/events/observer-design-pattern.md displayName: Observer design pattern + href: ../standard/events/observer-design-pattern.md - name: Best practices href: ../standard/events/observer-design-pattern-best-practices.md - - name: "How to: Implement a provider" + - name: 'How to: Implement a provider' href: ../standard/events/how-to-implement-a-provider.md - - name: "How to: Implement an observer" + - name: 'How to: Implement an observer' href: ../standard/events/how-to-implement-an-observer.md - name: Exceptions items: - name: Overview - href: ../standard/exceptions/index.md displayName: exceptions + href: ../standard/exceptions/index.md - name: Exception class and properties href: ../standard/exceptions/exception-class-and-properties.md - name: How-tos @@ -2000,8 +2000,8 @@ items: - name: Attributes items: - name: Overview - href: ../standard/attributes/index.md displayName: attributes + href: ../standard/attributes/index.md - name: Apply attributes href: ../standard/attributes/applying-attributes.md - name: Write custom attributes @@ -2063,8 +2063,8 @@ items: - name: Basic string operations items: - name: Overview - href: ../standard/base-types/basic-string-operations.md displayName: string operations + href: ../standard/base-types/basic-string-operations.md - name: Create new strings href: ../standard/base-types/creating-new.md - name: Trim and remove characters @@ -2079,7 +2079,7 @@ items: href: ../standard/base-types/divide-up-strings.md - name: Use the StringBuilder class href: ../standard/base-types/stringbuilder.md - - name: "How to: Perform basic string manipulations" + - name: 'How to: Perform basic string manipulations' href: ../standard/base-types/basic-manipulations.md - name: Parse (convert) strings items: @@ -2094,8 +2094,8 @@ items: - name: Regular expressions items: - name: Overview - href: ../standard/base-types/regular-expressions.md displayName: regular expressions + href: ../standard/base-types/regular-expressions.md - name: Language reference items: - name: Overview @@ -2153,8 +2153,8 @@ items: - name: JSON serialization items: - name: Overview - href: ../standard/serialization/system-text-json-overview.md displayName: json serialization + href: ../standard/serialization/system-text-json-overview.md - name: Reflection vs. source generation href: ../standard/serialization/system-text-json-source-generation-modes.md - name: How to serialize and deserialize JSON @@ -2196,8 +2196,8 @@ items: - name: Binary serialization items: - name: Overview - href: ../standard/serialization/binary-serialization.md displayName: binary serialization + href: ../standard/serialization/binary-serialization.md - name: BinaryFormatter security guide href: ../standard/serialization/binaryformatter-security-guide.md - name: BinaryFormatter event source @@ -2216,9 +2216,9 @@ items: href: ../standard/serialization/version-tolerant-serialization.md - name: Serialization guidelines href: ../standard/serialization/serialization-guidelines.md - - name: "How to: Chunk serialized data" + - name: 'How to: Chunk serialized data' href: ../standard/serialization/how-to-chunk-serialized-data.md - - name: "How to: Determine if a .NET Standard object is serializable" + - name: 'How to: Determine if a .NET Standard object is serializable' href: ../standard/serialization/how-to-determine-if-netstandard-object-is-serializable.md - name: XML and SOAP serialization items: @@ -2283,29 +2283,29 @@ items: - name: Common I/O tasks href: ../standard/io/common-i-o-tasks.md items: - - name: "How to: Copy Directories" + - name: 'How to: Copy Directories' href: ../standard/io/how-to-copy-directories.md - - name: "How to: Enumerate Directories and Files" + - name: 'How to: Enumerate Directories and Files' href: ../standard/io/how-to-enumerate-directories-and-files.md - - name: "How to: Read and Write to a Newly Created Data File" + - name: 'How to: Read and Write to a Newly Created Data File' href: ../standard/io/how-to-read-and-write-to-a-newly-created-data-file.md - - name: "How to: Open and Append to a Log File" + - name: 'How to: Open and Append to a Log File' href: ../standard/io/how-to-open-and-append-to-a-log-file.md - - name: "How to: Write Text to a File" + - name: 'How to: Write Text to a File' href: ../standard/io/how-to-write-text-to-a-file.md - - name: "How to: Read Text from a File" + - name: 'How to: Read Text from a File' href: ../standard/io/how-to-read-text-from-a-file.md - - name: "How to: Read Characters from a String" + - name: 'How to: Read Characters from a String' href: ../standard/io/how-to-read-characters-from-a-string.md - - name: "How to: Write Characters to a String" + - name: 'How to: Write Characters to a String' href: ../standard/io/how-to-write-characters-to-a-string.md - - name: "How to: Add or Remove Access Control List Entries" + - name: 'How to: Add or Remove Access Control List Entries' href: ../standard/io/how-to-add-or-remove-access-control-list-entries.md - - name: "How to: Compress and Extract Files" + - name: 'How to: Compress and Extract Files' href: ../standard/io/how-to-compress-and-extract-files.md - name: Composing Streams href: ../standard/io/composing-streams.md - - name: "How to: Convert Between .NET Framework Streams and Windows Runtime Streams" + - name: 'How to: Convert Between .NET Framework Streams and Windows Runtime Streams' href: ../standard/io/how-to-convert-between-dotnet-streams-and-winrt-streams.md - name: Asynchronous file I/O href: ../standard/io/asynchronous-file-i-o.md @@ -2316,28 +2316,28 @@ items: items: - name: Types of Isolation href: ../standard/io/types-of-isolation.md - - name: "How to: Obtain Stores for Isolated Storage" + - name: 'How to: Obtain Stores for Isolated Storage' href: ../standard/io/how-to-obtain-stores-for-isolated-storage.md - - name: "How to: Enumerate Stores for Isolated Storage" + - name: 'How to: Enumerate Stores for Isolated Storage' href: ../standard/io/how-to-enumerate-stores-for-isolated-storage.md - - name: "How to: Delete Stores in Isolated Storage" + - name: 'How to: Delete Stores in Isolated Storage' href: ../standard/io/how-to-delete-stores-in-isolated-storage.md - - name: "How to: Anticipate Out-of-Space Conditions with Isolated Storage" + - name: 'How to: Anticipate Out-of-Space Conditions with Isolated Storage' href: ../standard/io/how-to-anticipate-out-of-space-conditions-with-isolated-storage.md - - name: "How to: Create Files and Directories in Isolated Storage" + - name: 'How to: Create Files and Directories in Isolated Storage' href: ../standard/io/how-to-create-files-and-directories-in-isolated-storage.md - - name: "How to: Find Existing Files and Directories in Isolated Storage" + - name: 'How to: Find Existing Files and Directories in Isolated Storage' href: ../standard/io/how-to-find-existing-files-and-directories-in-isolated-storage.md - - name: "How to: Read and Write to Files in Isolated Storage" + - name: 'How to: Read and Write to Files in Isolated Storage' href: ../standard/io/how-to-read-and-write-to-files-in-isolated-storage.md - - name: "How to: Delete Files and Directories in Isolated Storage" + - name: 'How to: Delete Files and Directories in Isolated Storage' href: ../standard/io/how-to-delete-files-and-directories-in-isolated-storage.md - name: Pipes href: ../standard/io/pipe-operations.md items: - - name: "How to: Use Anonymous Pipes for Local Interprocess Communication" + - name: 'How to: Use Anonymous Pipes for Local Interprocess Communication' href: ../standard/io/how-to-use-anonymous-pipes-for-local-interprocess-communication.md - - name: "How to: Use Named Pipes for Network Interprocess Communication" + - name: 'How to: Use Named Pipes for Network Interprocess Communication' href: ../standard/io/how-to-use-named-pipes-for-network-interprocess-communication.md - name: Pipelines href: ../standard/io/pipelines.md @@ -2350,25 +2350,25 @@ items: - name: Dependency injection items: - name: Overview - href: ../core/extensions/dependency-injection.md displayName: dependency injection,di,ioc,ioc container,dependency container,inversion of control + href: ../core/extensions/dependency-injection.md - name: Use dependency injection - href: ../core/extensions/dependency-injection-usage.md displayName: use dependency injection,di,di examples,ioc,ioc container,dependency container,inversion of control + href: ../core/extensions/dependency-injection-usage.md - name: Dependency injection guidelines - href: ../core/extensions/dependency-injection-guidelines.md displayName: dependency injection best practices,guidelines,di,ioc,ioc container,dependency container,inversion of control + href: ../core/extensions/dependency-injection-guidelines.md - name: Configuration items: - name: Overview - href: ../core/extensions/configuration.md displayName: configuration,config,configuration sources,config sources + href: ../core/extensions/configuration.md - name: Configuration providers - href: ../core/extensions/configuration-providers.md displayName: configuration providers,config providers + href: ../core/extensions/configuration-providers.md - name: Implement a custom configuration provider - href: ../core/extensions/custom-configuration-provider.md displayName: custom configuration,custom config,custom configuration provider,custom config provider + href: ../core/extensions/custom-configuration-provider.md - name: Options pattern href: ../core/extensions/options.md - name: Options pattern guidance for library authors @@ -2380,8 +2380,8 @@ items: - name: Logging providers href: ../core/extensions/logging-providers.md - name: Compile-time logging source generation - href: ../core/extensions/logger-message-generator.md displayName: LoggerMessage,LoggerMessageAttribute,source generator,compile-time generation + href: ../core/extensions/logger-message-generator.md - name: Implement a custom logging provider href: ../core/extensions/custom-logging-provider.md - name: High-performance logging @@ -2466,12 +2466,12 @@ items: - name: Microsoft.Data.Sqlite href: ../standard/data/sqlite/ - name: Entity Framework Core - href: "/ef/core/" + href: /ef/core/ - name: Parallel processing, concurrency, and async items: - name: Overview - href: ../standard/parallel-processing-and-concurrency.md displayName: Parallel processing, concurrency, async + href: ../standard/parallel-processing-and-concurrency.md - name: Asynchronous programming items: - name: Overview @@ -2490,21 +2490,21 @@ items: - name: Data parallelism href: ../standard/parallel-programming/data-parallelism-task-parallel-library.md items: - - name: "How to: Write a Simple Parallel.For Loop" + - name: 'How to: Write a Simple Parallel.For Loop' href: ../standard/parallel-programming/how-to-write-a-simple-parallel-for-loop.md - - name: "How to: Write a Simple Parallel.ForEach Loop" + - name: 'How to: Write a Simple Parallel.ForEach Loop' href: ../standard/parallel-programming/how-to-write-a-simple-parallel-foreach-loop.md - - name: "How to: Write a Parallel.For Loop with Thread-Local Variables" + - name: 'How to: Write a Parallel.For Loop with Thread-Local Variables' href: ../standard/parallel-programming/how-to-write-a-parallel-for-loop-with-thread-local-variables.md - - name: "How to: Write a Parallel.ForEach Loop with Partition-Local Variables" + - name: 'How to: Write a Parallel.ForEach Loop with Partition-Local Variables' href: ../standard/parallel-programming/how-to-write-a-parallel-foreach-loop-with-partition-local-variables.md - - name: "How to: Cancel a Parallel.For or ForEach Loop" + - name: 'How to: Cancel a Parallel.For or ForEach Loop' href: ../standard/parallel-programming/how-to-cancel-a-parallel-for-or-foreach-loop.md - - name: "How to: Handle Exceptions in Parallel Loops" + - name: 'How to: Handle Exceptions in Parallel Loops' href: ../standard/parallel-programming/how-to-handle-exceptions-in-parallel-loops.md - - name: "How to: Speed Up Small Loop Bodies" + - name: 'How to: Speed Up Small Loop Bodies' href: ../standard/parallel-programming/how-to-speed-up-small-loop-bodies.md - - name: "How to: Iterate File Directories with the Parallel Class" + - name: 'How to: Iterate File Directories with the Parallel Class' href: ../standard/parallel-programming/how-to-iterate-file-directories-with-the-parallel-class.md - name: Task-based asynchronous programming href: ../standard/parallel-programming/task-based-asynchronous-programming.md @@ -2517,52 +2517,52 @@ items: href: ../standard/parallel-programming/task-cancellation.md - name: Exception Handling href: ../standard/parallel-programming/exception-handling-task-parallel-library.md - - name: "How to: Use Parallel.Invoke to Execute Parallel Operations" + - name: 'How to: Use Parallel.Invoke to Execute Parallel Operations' href: ../standard/parallel-programming/how-to-use-parallel-invoke-to-execute-parallel-operations.md - - name: "How to: Return a Value from a Task" + - name: 'How to: Return a Value from a Task' href: ../standard/parallel-programming/how-to-return-a-value-from-a-task.md - - name: "How to: Cancel a Task and Its Children" + - name: 'How to: Cancel a Task and Its Children' href: ../standard/parallel-programming/how-to-cancel-a-task-and-its-children.md - - name: "How to: Create Pre-Computed Tasks" + - name: 'How to: Create Pre-Computed Tasks' href: ../standard/parallel-programming/how-to-create-pre-computed-tasks.md - - name: "How to: Traverse a Binary Tree with Parallel Tasks" + - name: 'How to: Traverse a Binary Tree with Parallel Tasks' href: ../standard/parallel-programming/how-to-traverse-a-binary-tree-with-parallel-tasks.md - - name: "How to: Unwrap a Nested Task" + - name: 'How to: Unwrap a Nested Task' href: ../standard/parallel-programming/how-to-unwrap-a-nested-task.md - - name: "How to: Prevent a Child Task from Attaching to its Parent" + - name: 'How to: Prevent a Child Task from Attaching to its Parent' href: ../standard/parallel-programming/how-to-prevent-a-child-task-from-attaching-to-its-parent.md - name: Dataflow href: ../standard/parallel-programming/dataflow-task-parallel-library.md items: - - name: "How to: Write Messages to and Read Messages from a Dataflow Block" + - name: 'How to: Write Messages to and Read Messages from a Dataflow Block' href: ../standard/parallel-programming/how-to-write-messages-to-and-read-messages-from-a-dataflow-block.md - - name: "How to: Implement a Producer-Consumer Dataflow Pattern" + - name: 'How to: Implement a Producer-Consumer Dataflow Pattern' href: ../standard/parallel-programming/how-to-implement-a-producer-consumer-dataflow-pattern.md - - name: "How to: Perform Action When a Dataflow Block Receives Data" + - name: 'How to: Perform Action When a Dataflow Block Receives Data' href: ../standard/parallel-programming/how-to-perform-action-when-a-dataflow-block-receives-data.md - - name: "Walkthrough: Creating a Dataflow Pipeline" + - name: 'Walkthrough: Creating a Dataflow Pipeline' href: ../standard/parallel-programming/walkthrough-creating-a-dataflow-pipeline.md - - name: "How to: Unlink Dataflow Blocks" + - name: 'How to: Unlink Dataflow Blocks' href: ../standard/parallel-programming/how-to-unlink-dataflow-blocks.md - - name: "Walkthrough: Using Dataflow in a Windows Forms Application" + - name: 'Walkthrough: Using Dataflow in a Windows Forms Application' href: ../standard/parallel-programming/walkthrough-using-dataflow-in-a-windows-forms-application.md - - name: "How to: Cancel a Dataflow Block" + - name: 'How to: Cancel a Dataflow Block' href: ../standard/parallel-programming/how-to-cancel-a-dataflow-block.md - - name: "Walkthrough: Creating a Custom Dataflow Block Type" + - name: 'Walkthrough: Creating a Custom Dataflow Block Type' href: ../standard/parallel-programming/walkthrough-creating-a-custom-dataflow-block-type.md - - name: "How to: Use JoinBlock to Read Data From Multiple Sources" + - name: 'How to: Use JoinBlock to Read Data From Multiple Sources' href: ../standard/parallel-programming/how-to-use-joinblock-to-read-data-from-multiple-sources.md - - name: "How to: Specify the Degree of Parallelism in a Dataflow Block" + - name: 'How to: Specify the Degree of Parallelism in a Dataflow Block' href: ../standard/parallel-programming/how-to-specify-the-degree-of-parallelism-in-a-dataflow-block.md - - name: "How to: Specify a Task Scheduler in a Dataflow Block" + - name: 'How to: Specify a Task Scheduler in a Dataflow Block' href: ../standard/parallel-programming/how-to-specify-a-task-scheduler-in-a-dataflow-block.md - - name: "Walkthrough: Using BatchBlock and BatchedJoinBlock to Improve Efficiency" + - name: 'Walkthrough: Using BatchBlock and BatchedJoinBlock to Improve Efficiency' href: ../standard/parallel-programming/walkthrough-using-batchblock-and-batchedjoinblock-to-improve-efficiency.md - name: Use TPL with Other Asynchronous Patterns items: - name: TPL and Traditional .NET Asynchronous Programming href: ../standard/parallel-programming/tpl-and-traditional-async-programming.md - - name: "How to: Wrap EAP Patterns in a Task" + - name: 'How to: Wrap EAP Patterns in a Task' href: ../standard/parallel-programming/how-to-wrap-eap-patterns-in-a-task.md - name: Potential Pitfalls in Data and Task Parallelism href: ../standard/parallel-programming/potential-pitfalls-in-data-and-task-parallelism.md @@ -2578,25 +2578,25 @@ items: href: ../standard/parallel-programming/merge-options-in-plinq.md - name: Potential Pitfalls with PLINQ href: ../standard/parallel-programming/potential-pitfalls-with-plinq.md - - name: "How to: Create and Execute a Simple PLINQ Query" + - name: 'How to: Create and Execute a Simple PLINQ Query' href: ../standard/parallel-programming/how-to-create-and-execute-a-simple-plinq-query.md - - name: "How to: Control Ordering in a PLINQ Query" + - name: 'How to: Control Ordering in a PLINQ Query' href: ../standard/parallel-programming/how-to-control-ordering-in-a-plinq-query.md - - name: "How to: Combine Parallel and Sequential LINQ Queries" + - name: 'How to: Combine Parallel and Sequential LINQ Queries' href: ../standard/parallel-programming/how-to-combine-parallel-and-sequential-linq-queries.md - - name: "How to: Handle Exceptions in a PLINQ Query" + - name: 'How to: Handle Exceptions in a PLINQ Query' href: ../standard/parallel-programming/how-to-handle-exceptions-in-a-plinq-query.md - - name: "How to: Cancel a PLINQ Query" + - name: 'How to: Cancel a PLINQ Query' href: ../standard/parallel-programming/how-to-cancel-a-plinq-query.md - - name: "How to: Write a Custom PLINQ Aggregate Function" + - name: 'How to: Write a Custom PLINQ Aggregate Function' href: ../standard/parallel-programming/how-to-write-a-custom-plinq-aggregate-function.md - - name: "How to: Specify the Execution Mode in PLINQ" + - name: 'How to: Specify the Execution Mode in PLINQ' href: ../standard/parallel-programming/how-to-specify-the-execution-mode-in-plinq.md - - name: "How to: Specify Merge Options in PLINQ" + - name: 'How to: Specify Merge Options in PLINQ' href: ../standard/parallel-programming/how-to-specify-merge-options-in-plinq.md - - name: "How to: Iterate File Directories with PLINQ" + - name: 'How to: Iterate File Directories with PLINQ' href: ../standard/parallel-programming/how-to-iterate-file-directories-with-plinq.md - - name: "How to: Measure PLINQ Query Performance" + - name: 'How to: Measure PLINQ Query Performance' href: ../standard/parallel-programming/how-to-measure-plinq-query-performance.md - name: PLINQ Data Sample href: ../standard/parallel-programming/plinq-data-sample.md @@ -2607,11 +2607,11 @@ items: - name: Custom partitioners for PLINQ and TPL items: - name: Overview - href: ../standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md displayName: custom partitioners - - name: "How to: Implement Dynamic Partitions" + href: ../standard/parallel-programming/custom-partitioners-for-plinq-and-tpl.md + - name: 'How to: Implement Dynamic Partitions' href: ../standard/parallel-programming/how-to-implement-dynamic-partitions.md - - name: "How to: Implement a Partitioner for Static Partitioning" + - name: 'How to: Implement a Partitioner for Static Partitioning' href: ../standard/parallel-programming/how-to-implement-a-partitioner-for-static-partitioning.md - name: Lambda expressions in PLINQ and TPL href: ../standard/parallel-programming/lambda-expressions-in-plinq-and-tpl.md @@ -2635,8 +2635,8 @@ items: - name: VB unit testing href: ../core/testing/unit-testing-visual-basic-with-dotnet-test.md - name: Organize a project and test with xUnit - href: ../core/tutorials/testing-with-cli.md displayName: tutorials, cli + href: ../core/tutorials/testing-with-cli.md - name: NUnit items: - name: C# unit testing @@ -2678,21 +2678,21 @@ items: - name: Clean up unmanaged resources items: - name: Overview - href: ../standard/garbage-collection/unmanaged.md displayName: unmanaged resources, memory management + href: ../standard/garbage-collection/unmanaged.md - name: Implement a Dispose method + displayName: using, Dispose, dispose pattern, IDisposable href: ../standard/garbage-collection/implementing-dispose.md - displayName: "using, Dispose, dispose pattern, IDisposable" - name: Implement a DisposeAsync method + displayName: await using, DisposeAsync, async dispose pattern, IAsyncDisposable href: ../standard/garbage-collection/implementing-disposeasync.md - displayName: "await using, DisposeAsync, async dispose pattern, IAsyncDisposable" - name: Use objects that implement IDisposable href: ../standard/garbage-collection/using-objects.md - name: Garbage collection items: - name: Overview - href: ../standard/garbage-collection/index.md displayName: garbage collection + href: ../standard/garbage-collection/index.md - name: Fundamentals href: ../standard/garbage-collection/fundamentals.md - name: Workstation and server GC @@ -2726,8 +2726,8 @@ items: - name: Native interoperability items: - name: Overview - href: ../standard/native-interop/index.md displayName: Native interop + href: ../standard/native-interop/index.md - name: P/Invoke href: ../standard/native-interop/pinvoke.md - name: Type marshaling @@ -2749,13 +2749,13 @@ items: - name: COM interop items: - name: Overview - href: ../standard/native-interop/cominterop.md displayName: COM interop + href: ../standard/native-interop/cominterop.md - name: COM wrappers items: - name: Overview - href: ../standard/native-interop/com-wrappers.md displayName: COM wrappers + href: ../standard/native-interop/com-wrappers.md - name: Runtime-callable wrapper href: ../standard/native-interop/runtime-callable-wrapper.md - name: COM-callable wrapper @@ -2772,111 +2772,6 @@ items: href: ../core/distribution-packaging.md - name: Open-source library guidance href: ../standard/library-guidance/ - - name: Framework design guidelines - items: - - name: Overview - href: ../standard/design-guidelines/index.md - - name: Naming guidelines - href: ../standard/design-guidelines/naming-guidelines.md - items: - - name: Capitalization conventions - href: ../standard/design-guidelines/capitalization-conventions.md - - name: General naming conventions - href: ../standard/design-guidelines/general-naming-conventions.md - - name: Names of assemblies and DLLs - href: ../standard/design-guidelines/names-of-assemblies-and-dlls.md - - name: Names of namespaces - href: ../standard/design-guidelines/names-of-namespaces.md - - name: Names of classes, structs, and interfaces - href: ../standard/design-guidelines/names-of-classes-structs-and-interfaces.md - - name: Names of type members - href: ../standard/design-guidelines/names-of-type-members.md - - name: Naming parameters - href: ../standard/design-guidelines/naming-parameters.md - - name: Naming resources - href: ../standard/design-guidelines/naming-resources.md - - name: Type design guidelines - href: ../standard/design-guidelines/type.md - items: - - name: Choose between class and struct - href: ../standard/design-guidelines/choosing-between-class-and-struct.md - - name: Abstract class design - href: ../standard/design-guidelines/abstract-class.md - - name: Static class design - href: ../standard/design-guidelines/static-class.md - - name: Interface design - href: ../standard/design-guidelines/interface.md - - name: Struct design - href: ../standard/design-guidelines/struct.md - - name: Enum design - href: ../standard/design-guidelines/enum.md - - name: Nested types - href: ../standard/design-guidelines/nested-types.md - - name: Member design guidelines - href: ../standard/design-guidelines/member.md - items: - - name: Member overloading - href: ../standard/design-guidelines/member-overloading.md - - name: Property design - href: ../standard/design-guidelines/property.md - - name: Constructor design - href: ../standard/design-guidelines/constructor.md - - name: Event design - href: ../standard/design-guidelines/event.md - - name: Field design - href: ../standard/design-guidelines/field.md - - name: Extension methods - href: ../standard/design-guidelines/extension-methods.md - - name: Operator overloads - href: ../standard/design-guidelines/operator-overloads.md - - name: Parameter design - href: ../standard/design-guidelines/parameter-design.md - - name: Design for extensibility - href: ../standard/design-guidelines/designing-for-extensibility.md - items: - - name: Unsealed classes - href: ../standard/design-guidelines/unsealed-classes.md - - name: Protected members - href: ../standard/design-guidelines/protected-members.md - - name: Events and callbacks - href: ../standard/design-guidelines/events-and-callbacks.md - - name: Virtual members - href: ../standard/design-guidelines/virtual-members.md - - name: Abstractions (abstract types and interfaces) - href: ../standard/design-guidelines/abstractions-abstract-types-and-interfaces.md - - name: Base classes for implementing abstractions - href: ../standard/design-guidelines/base-classes-for-implementing-abstractions.md - - name: Sealing - href: ../standard/design-guidelines/sealing.md - - name: Exception design guidelines - href: ../standard/design-guidelines/exceptions.md - items: - - name: Exception throwing - href: ../standard/design-guidelines/exception-throwing.md - - name: Use standard exception types - href: ../standard/design-guidelines/using-standard-exception-types.md - - name: Exceptions and performance - href: ../standard/design-guidelines/exceptions-and-performance.md - - name: Usage guidelines - href: ../standard/design-guidelines/usage-guidelines.md - items: - - name: Arrays - href: ../standard/design-guidelines/arrays.md - - name: Attributes - href: ../standard/design-guidelines/attributes.md - - name: Collections - href: ../standard/design-guidelines/guidelines-for-collections.md - - name: Serialization - href: ../standard/design-guidelines/serialization.md - - name: System.Xml usage - href: ../standard/design-guidelines/system-xml-usage.md - - name: Equality operators - href: ../standard/design-guidelines/equality-operators.md - - name: Common design patterns - href: ../standard/design-guidelines/common-design-patterns.md - items: - - name: Dependency properties - href: ../standard/design-guidelines/dependency-properties.md - name: Migration guide items: - name: Overview diff --git a/docs/standard/base-types/choosing-between-anonymous-and-tuple.md b/docs/standard/base-types/choosing-between-anonymous-and-tuple.md index b30206f8819c7..cba4aa3d6f810 100644 --- a/docs/standard/base-types/choosing-between-anonymous-and-tuple.md +++ b/docs/standard/base-types/choosing-between-anonymous-and-tuple.md @@ -118,4 +118,4 @@ As a developer choosing between tuples and anonymous types, there are several fa - [Expression trees](../../csharp/expression-trees.md) - [Tuple types (C# reference)](../../csharp/language-reference/builtin-types/value-tuples.md) - [Tuples (Visual Basic)](../../visual-basic/programming-guide/language-features/data-types/tuples.md) -- [Type design guidelines](../design-guidelines/type.md) +- [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines) diff --git a/docs/standard/design-guidelines/abstract-class.md b/docs/standard/design-guidelines/abstract-class.md deleted file mode 100644 index 4006013d5c3aa..0000000000000 --- a/docs/standard/design-guidelines/abstract-class.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -description: "Learn more about: Abstract Class Design" -title: "Abstract Class Design" -ms.date: "10/22/2008" -helpviewer_keywords: - - "type design guidelines, abstract classes" - - "abstract classes, design guidelines" - - "class library design guidelines [.NET Framework], classes" - - "classes [.NET Framework], abstract" - - "classes [.NET Framework], design guidelines" - - "type design guidelines, classes" -ms.assetid: d3646e6d-5c1f-4922-8fb0-ec5effb30d60 ---- -# Abstract Class Design - -❌ DO NOT define public or protected internal constructors in abstract types. - - Constructors should be public only if users will need to create instances of the type. Because you cannot create instances of an abstract type, an abstract type with a public constructor is incorrectly designed and misleading to the users. - - ✔️ DO define a protected or an internal constructor in abstract classes. - - A protected constructor is more common and simply allows the base class to do its own initialization when subtypes are created. - - An internal constructor can be used to limit concrete implementations of the abstract class to the assembly defining the class. - - ✔️ DO provide at least one concrete type that inherits from each abstract class that you ship. - - Doing this helps to validate the design of the abstract class. For example, is an implementation of the abstract class. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Type Design Guidelines](type.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/abstractions-abstract-types-and-interfaces.md b/docs/standard/design-guidelines/abstractions-abstract-types-and-interfaces.md deleted file mode 100644 index 5c1360b667c14..0000000000000 --- a/docs/standard/design-guidelines/abstractions-abstract-types-and-interfaces.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -description: "Learn more about: Abstractions (Abstract Types and Interfaces)" -title: "Abstractions (Abstract Types and Interfaces)" -ms.date: "10/22/2008" -helpviewer_keywords: - - "interfaces [.NET Framework], abstract" - - "abstract interfaces [.NET Framework]" - - "abstract types [.NET Framework]" - - "types [.NET Framework], abstract" -ms.assetid: 0a632bc7-9b03-44ee-8842-c82f88672a45 ---- -# Abstractions (Abstract Types and Interfaces) - -An abstraction is a type that describes a contract but does not provide a full implementation of the contract. Abstractions are usually implemented as abstract classes or interfaces, and they come with a well-defined set of reference documentation describing the required semantics of the types implementing the contract. Some of the most important abstractions in the .NET Framework include , , and . - - You can extend frameworks by implementing a concrete type that supports the contract of an abstraction and using this concrete type with framework APIs consuming (operating on) the abstraction. - - A meaningful and useful abstraction that is able to withstand the test of time is very difficult to design. The main difficulty is getting the right set of members, no more and no fewer. If an abstraction has too many members, it becomes difficult or even impossible to implement. If it has too few members for the promised functionality, it becomes useless in many interesting scenarios. - - Too many abstractions in a framework also negatively affect usability of the framework. It is often quite difficult to understand an abstraction without understanding how it fits into the larger picture of the concrete implementations and the APIs operating on the abstraction. Also, names of abstractions and their members are necessarily abstract, which often makes them cryptic and unapproachable without first understanding the broader context of their usage. - - However, abstractions provide extremely powerful extensibility that the other extensibility mechanisms cannot often match. They are at the core of many architectural patterns, such as plug-ins, inversion of control (IoC), pipelines, and so on. They are also extremely important for testability of frameworks. Good abstractions make it possible to stub out heavy dependencies for the purpose of unit testing. In summary, abstractions are responsible for the sought-after richness of the modern object-oriented frameworks. - - ❌ DO NOT provide abstractions unless they are tested by developing several concrete implementations and APIs consuming the abstractions. - - ✔️ DO choose carefully between an abstract class and an interface when designing an abstraction. - - ✔️ CONSIDER providing reference tests for concrete implementations of abstractions. Such tests should allow users to test whether their implementations correctly implement the contract. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Designing for Extensibility](designing-for-extensibility.md) diff --git a/docs/standard/design-guidelines/arrays.md b/docs/standard/design-guidelines/arrays.md deleted file mode 100644 index 9ba12b709bbef..0000000000000 --- a/docs/standard/design-guidelines/arrays.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: "Learn more about design guidelines for arrays" -title: "Arrays (.NET Framework design guidelines)" -titleSuffix: "" -ms.date: "10/22/2008" -helpviewer_keywords: - - "class library design guidelines [.NET Framework], arrays" - - "arrays [.NET Framework], usage guidelines" - - "empty arrays" ---- -# Arrays (.NET Framework design guidelines) - -✔️ DO prefer using collections over arrays in public APIs. The [Collections](guidelines-for-collections.md) section provides details about how to choose between collections and arrays. - - ❌ DO NOT use read-only array fields. The field itself is read-only and can't be changed, but elements in the array can be changed. - - ✔️ CONSIDER using jagged arrays instead of multidimensional arrays. - - A jagged array is an array with elements that are also arrays. The arrays that make up the elements can be of different sizes, leading to less wasted space for some sets of data (e.g., sparse matrix) compared to multidimensional arrays. Furthermore, the CLR optimizes index operations on jagged arrays, so they might exhibit better runtime performance in some scenarios. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- -- [Framework Design Guidelines](index.md) -- [Usage Guidelines](usage-guidelines.md) diff --git a/docs/standard/design-guidelines/attributes.md b/docs/standard/design-guidelines/attributes.md deleted file mode 100644 index 1b7c4d0d0ca9a..0000000000000 --- a/docs/standard/design-guidelines/attributes.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -description: "Learn more about design guidelines for attributes" -title: "Attributes" -ms.date: "10/22/2008" -helpviewer_keywords: - - "attributes [.NET Framework], about" - - "class library design guidelines [.NET Framework], attributes" -ms.assetid: ee0038ef-b247-4747-a650-3c5c5cd58d8b ---- -# Attributes (.NET Framework design guidelines) - - is a base class used to define custom attributes. - - Attributes are annotations that can be added to programming elements such as assemblies, types, members, and parameters. They are stored in the metadata of the assembly and can be accessed at run time using the reflection APIs. For example, the Framework defines the , which can be applied to a type or a member to indicate that the type or member has been deprecated. - - Attributes can have one or more properties that carry additional data related to the attribute. For example, `ObsoleteAttribute` could carry additional information about the release in which a type or a member got deprecated and the description of the new APIs replacing the obsolete API. - - Some properties of an attribute must be specified when the attribute is applied. These are referred to as the required properties or required arguments, because they are represented as positional constructor parameters. For example, the property of the is a required property. - - Properties that do not necessarily have to be specified when the attribute is applied are called optional properties (or optional arguments). They are represented by settable properties. Compilers provide special syntax to set these properties when an attribute is applied. For example, the property represents an optional argument. - - ✔️ DO name custom attribute classes with the suffix "Attribute." - - ✔️ DO apply the to custom attributes. - - ✔️ DO provide settable properties for optional arguments. - - ✔️ DO provide get-only properties for required arguments. - - ✔️ DO provide constructor parameters to initialize properties corresponding to required arguments. Each parameter should have the same name (although with different casing) as the corresponding property. - - ❌ AVOID providing constructor parameters to initialize properties corresponding to the optional arguments. - - In other words, do not have properties that can be set with both a constructor and a setter. This guideline makes very explicit which arguments are optional and which are required, and avoids having two ways of doing the same thing. - - ❌ AVOID overloading custom attribute constructors. - - Having only one constructor clearly communicates to the user which arguments are required and which are optional. - - ✔️ DO seal custom attribute classes, if possible. This makes the look-up for the attribute faster. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Usage Guidelines](usage-guidelines.md) diff --git a/docs/standard/design-guidelines/base-classes-for-implementing-abstractions.md b/docs/standard/design-guidelines/base-classes-for-implementing-abstractions.md deleted file mode 100644 index 9a18929928016..0000000000000 --- a/docs/standard/design-guidelines/base-classes-for-implementing-abstractions.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: "Learn more about: Base Classes for Implementing Abstractions" -title: "Base Classes for Implementing Abstractions" -ms.date: "10/22/2008" -helpviewer_keywords: - - "abstractions [.NET Framework]" - - "base classes, abstractions" -ms.assetid: 37a2d9a4-9721-482a-a40f-eee2c1d97875 ---- -# Base Classes for Implementing Abstractions - -Strictly speaking, a class becomes a base class when another class is derived from it. For the purpose of this section, however, a base class is a class designed mainly to provide a common abstraction or for other classes to reuse some default implementation though inheritance. Base classes usually sit in the middle of inheritance hierarchies, between an abstraction at the root of a hierarchy and several custom implementations at the bottom. - - They serve as implementation helpers for implementing abstractions. For example, one of the Framework’s abstractions for ordered collections of items is the interface. Implementing is not trivial, and therefore the Framework provides several base classes, such as and , which serve as helpers for implementing custom collections. - - Base classes are usually not suited to serve as abstractions by themselves, because they tend to contain too much implementation. For example, the `Collection` base class contains lots of implementation related to the fact that it implements the nongeneric `IList` interface (to integrate better with nongeneric collections) and to the fact that it is a collection of items stored in memory in one of its fields. - - As previously discussed, base classes can provide invaluable help for users who need to implement abstractions, but at the same time they can be a significant liability. They add surface area and increase the depth of inheritance hierarchies and so conceptually complicate the framework. Therefore, base classes should be used only if they provide significant value to the users of the framework. They should be avoided if they provide value only to the implementers of the framework, in which case delegation to an internal implementation instead of inheritance from a base class should be strongly considered. - - ✔️ CONSIDER making base classes abstract even if they don’t contain any abstract members. This clearly communicates to the users that the class is designed solely to be inherited from. - - ✔️ CONSIDER placing base classes in a separate namespace from the mainline scenario types. By definition, base classes are intended for advanced extensibility scenarios and therefore are not interesting to the majority of users. - - ❌ AVOID naming base classes with a "Base" suffix if the class is intended for use in public APIs. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Designing for Extensibility](designing-for-extensibility.md) diff --git a/docs/standard/design-guidelines/capitalization-conventions.md b/docs/standard/design-guidelines/capitalization-conventions.md deleted file mode 100644 index 782bded30a972..0000000000000 --- a/docs/standard/design-guidelines/capitalization-conventions.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "Capitalization Conventions" -description: Apply capitalization conventions for identifiers, compound words, and common terms. Understand how case sensitivity works in .NET. -ms.date: "10/22/2008" -helpviewer_keywords: - - "camel-case names [.NET Framework]" - - "class library design guidelines [.NET Framework], capitalization" - - "Pascal-case names [.NET Framework]" - - "case sensitivity, capitalization conventions" - - "names [.NET Framework], capitalization" -ms.topic: reference ---- -# Capitalization Conventions - -The guidelines in this chapter lay out a simple method for using case that, when applied consistently, make identifiers for types, members, and parameters easy to read. - -## Capitalization Rules for Identifiers - - To differentiate words in an identifier, capitalize the first letter of each word in the identifier. Do not use underscores to differentiate words, or for that matter, anywhere in identifiers. There are two appropriate ways to capitalize identifiers, depending on the use of the identifier: - -- PascalCasing - -- camelCasing - - The PascalCasing convention, used for all identifiers except parameter names, capitalizes the first character of each word (including acronyms over two letters in length), as shown in the following examples: - - `PropertyDescriptor` - `HtmlTag` - - A special case is made for two-letter acronyms in which both letters are capitalized, as shown in the following identifier: - - `IOStream` - - The camelCasing convention, used only for parameter names, capitalizes the first character of each word except the first word, as shown in the following examples. As the example also shows, two-letter acronyms that begin a camel-cased identifier are both lowercase. - - `propertyDescriptor` - `ioStream` - `htmlTag` - - ✔️ DO use PascalCasing for all public member, type, and namespace names consisting of multiple words. - - ✔️ DO use camelCasing for parameter names. - - The following table describes the capitalization rules for different types of identifiers. - -|Identifier|Casing|Example| -|----------------|------------|-------------| -|Namespace|Pascal|`namespace System.Security { ... }`| -|Type|Pascal|`public class StreamReader { ... }`| -|Interface|Pascal|`public interface IEnumerable { ... }`| -|Method|Pascal|`public class Object {`
`public virtual string ToString();`
`}`| -|Property|Pascal|`public class String {`
`public int Length { get; }`
`}`| -|Event|Pascal|`public class Process {`
`public event EventHandler Exited;`
`}`| -|Field|Pascal|`public class MessageQueue {`
`public static readonly TimeSpan`
`InfiniteTimeout;`
`}`
`public struct UInt32 {`
`public const Min = 0;`
`}`| -|Enum value|Pascal|`public enum FileMode {`
`Append,`
`...`
`}`| -|Parameter|Camel|`public class Convert {`
`public static int ToInt32(string value);`
`}`| - -## Capitalizing Compound Words and Common Terms - - Most compound terms are treated as single words for purposes of capitalization. - - ❌ DO NOT capitalize each word in so-called closed-form compound words. - - These are compound words written as a single word, such as endpoint. For the purpose of casing guidelines, treat a closed-form compound word as a single word. Use a current dictionary to determine if a compound word is written in closed form. - -|Pascal|Camel|Not| -|------------|-----------|---------| -|`BitFlag`|`bitFlag`|`Bitflag`| -|`Callback`|`callback`|`CallBack`| -|`Canceled`|`canceled`|`Cancelled`| -|`DoNot`|`doNot`|`Don't`| -|`Email`|`email`|`EMail`| -|`Endpoint`|`endpoint`|`EndPoint`| -|`FileName`|`fileName`|`Filename`| -|`Gridline`|`gridline`|`GridLine`| -|`Hashtable`|`hashtable`|`HashTable`| -|`Id`|`id`|`ID`| -|`Indexes`|`indexes`|`Indices`| -|`LogOff`|`logOff`|`LogOut`| -|`LogOn`|`logOn`|`LogIn`| -|`Metadata`|`metadata`|`MetaData, metaData`| -|`Multipanel`|`multipanel`|`MultiPanel`| -|`Multiview`|`multiview`|`MultiView`| -|`Namespace`|`namespace`|`NameSpace`| -|`Ok`|`ok`|`OK`| -|`Pi`|`pi`|`PI`| -|`Placeholder`|`placeholder`|`PlaceHolder`| -|`SignIn`|`signIn`|`SignOn`| -|`SignOut`|`signOut`|`SignOff`| -|`UserName`|`userName`|`Username`| -|`WhiteSpace`|`whiteSpace`|`Whitespace`| -|`Writable`|`writable`|`Writeable`| - -## Case Sensitivity - - Languages that can run on the CLR are not required to support case-sensitivity, although some do. Even if your language supports it, other languages that might access your framework do not. Any APIs that are externally accessible, therefore, cannot rely on case alone to distinguish between two names in the same context. - - ❌ DO NOT assume that all programming languages are case sensitive. They are not. Names cannot differ by case alone. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Naming Guidelines](naming-guidelines.md) diff --git a/docs/standard/design-guidelines/choosing-between-class-and-struct.md b/docs/standard/design-guidelines/choosing-between-class-and-struct.md deleted file mode 100644 index dedf365ce92c2..0000000000000 --- a/docs/standard/design-guidelines/choosing-between-class-and-struct.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "Choosing Between Class and Struct" -description: Learn how to decide whether to design a type as a class, or to design a type as a struct. Understand how reference types and value types differ in .NET. -ms.date: "10/22/2008" -helpviewer_keywords: - - "class library design guidelines [.NET Framework], structures" - - "class library design guidelines [.NET Framework], classes" - - "structures [.NET Framework], vs. classes" - - "classes [.NET Framework], design guidelines" - - "type design guidelines, structures" - - "structures [.NET Framework], design guidelines" - - "classes [.NET Framework], vs. structures" - - "type design guidelines, classes" -ms.assetid: f8b8ec9b-0ba7-4dea-aadf-a93395cd804f ---- -# Choosing Between Class and Struct - -One of the basic design decisions every framework designer faces is whether to design a type as a class (a reference type) or as a struct (a value type). Good understanding of the differences in the behavior of reference types and value types is crucial in making this choice. - - The first difference between reference types and value types we will consider is that reference types are allocated on the heap and garbage-collected, whereas value types are allocated either on the stack or inline in containing types and deallocated when the stack unwinds or when their containing type gets deallocated. Therefore, allocations and deallocations of value types are in general cheaper than allocations and deallocations of reference types. - - Next, arrays of reference types are allocated out-of-line, meaning the array elements are just references to instances of the reference type residing on the heap. Value type arrays are allocated inline, meaning that the array elements are the actual instances of the value type. Therefore, allocations and deallocations of value type arrays are much cheaper than allocations and deallocations of reference type arrays. In addition, in a majority of cases value type arrays exhibit much better locality of reference. - - The next difference is related to memory usage. Value types get boxed when cast to a reference type or one of the interfaces they implement. They get unboxed when cast back to the value type. Because boxes are objects that are allocated on the heap and are garbage-collected, too much boxing and unboxing can have a negative impact on the heap, the garbage collector, and ultimately the performance of the application. In contrast, no such boxing occurs as reference types are cast. (For more information, see [Boxing and Unboxing](../../csharp/programming-guide/types/boxing-and-unboxing.md)). - - Next, reference type assignments copy the reference, whereas value type assignments copy the entire value. Therefore, assignments of large reference types are cheaper than assignments of large value types. - - Finally, reference types are passed by reference, whereas value types are passed by value. Changes to an instance of a reference type affect all references pointing to the instance. Value type instances are copied when they are passed by value. When an instance of a value type is changed, it of course does not affect any of its copies. Because the copies are not created explicitly by the user but are implicitly created when arguments are passed or return values are returned, value types that can be changed can be confusing to many users. Therefore, value types should be immutable. - - As a rule of thumb, the majority of types in a framework should be classes. There are, however, some situations in which the characteristics of a value type make it more appropriate to use structs. - - ✔️ CONSIDER defining a struct instead of a class if instances of the type are small and commonly short-lived or are commonly embedded in other objects. - - ❌ AVOID defining a struct unless the type has all of the following characteristics: - -- It logically represents a single value, similar to primitive types (`int`, `double`, etc.). - -- It has an instance size under 16 bytes. - -- It is immutable. - -- It will not have to be boxed frequently. - - In all other cases, you should define your types as classes. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Type Design Guidelines](type.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/common-design-patterns.md b/docs/standard/design-guidelines/common-design-patterns.md deleted file mode 100644 index 1a827687fa341..0000000000000 --- a/docs/standard/design-guidelines/common-design-patterns.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: "Common Design Patterns" -description: "See links that describe a couple of common design patterns in .NET: dependency properties and the dispose pattern." -ms.date: "10/22/2008" -helpviewer_keywords: - - "design patterns in class libraries" - - "class library design guidelines [.NET Framework], design patterns" -ms.assetid: f7bd1361-4ab2-4132-972d-a044b8f197e1 ---- -# Common Design Patterns - -There are numerous books on software patterns, pattern languages, and antipatterns that address the very broad subject of patterns. Thus, this chapter provides guidelines and discussion related to a very limited set of patterns that are used frequently in the design of the .NET Framework APIs. - -## In This Section - - [Dependency Properties](dependency-properties.md) - [Dispose Pattern](../garbage-collection/implementing-dispose.md) - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/constructor.md b/docs/standard/design-guidelines/constructor.md deleted file mode 100644 index 162bad7cfa036..0000000000000 --- a/docs/standard/design-guidelines/constructor.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -description: "Learn more about: Constructor Design" -title: "Constructor Design" -ms.date: "10/22/2008" -helpviewer_keywords: - - "member design guidelines, constructors" - - "constructors, design guidelines" - - "instance constructors" - - "type constructors" - - "virtual members" - - "constructors, types" - - "parameterless constructors" - - "static constructors" -ms.assetid: b4496afe-5fa7-4bb0-85ca-70b0ef21e6fc ---- -# Constructor Design - -There are two kinds of constructors: type constructors and instance constructors. - -Type constructors are static and are run by the CLR before the type is used. Instance constructors run when an instance of a type is created. - -Type constructors cannot take any parameters. Instance constructors can. Instance constructors that don’t take any parameters are often called parameterless constructors. - -Constructors are the most natural way to create instances of a type. Most developers will search and try to use a constructor before they consider alternative ways of creating instances (such as factory methods). - -✔️ CONSIDER providing simple, ideally default, constructors. - -A simple constructor has a very small number of parameters, and all parameters are primitives or enums. Such simple constructors increase usability of the framework. - -✔️ CONSIDER using a static factory method instead of a constructor if the semantics of the desired operation do not map directly to the construction of a new instance, or if following the constructor design guidelines feels unnatural. - -✔️ DO use constructor parameters as shortcuts for setting main properties. - -There should be no difference in semantics between using the empty constructor followed by some property sets and using a constructor with multiple arguments. - -✔️ DO use the same name for constructor parameters and a property if the constructor parameters are used to simply set the property. - -The only difference between such parameters and the properties should be casing. - -✔️ DO minimal work in the constructor. - -Constructors should not do much work other than capture the constructor parameters. The cost of any other processing should be delayed until required. - -✔️ DO throw exceptions from instance constructors, if appropriate. - -✔️ DO explicitly declare the public parameterless constructor in classes, if such a constructor is required. - -If you don’t explicitly declare any constructors on a type, many languages (such as C#) will automatically add a public parameterless constructor. (Abstract classes get a protected constructor.) - -Adding a parameterized constructor to a class prevents the compiler from adding the parameterless constructor. This often causes accidental breaking changes. - -❌ AVOID explicitly defining parameterless constructors on structs. - -This makes array creation faster, because if the parameterless constructor is not defined, it does not have to be run on every slot in the array. Note that many compilers, including C#, don’t allow structs to have parameterless constructors for this reason. - -❌ AVOID calling virtual members on an object inside its constructor. - -Calling a virtual member will cause the most derived override to be called, even if the constructor of the most derived type has not been fully run yet. - -## Type Constructor Guidelines - -✔️ DO make static constructors private. - -A static constructor, also called a class constructor, is used to initialize a type. The CLR calls the static constructor before the first instance of the type is created or any static members on that type are called. The user has no control over when the static constructor is called. If a static constructor is not private, it can be called by code other than the CLR. Depending on the operations performed in the constructor, this can cause unexpected behavior. The C# compiler forces static constructors to be private. - -❌ DO NOT throw exceptions from static constructors. - -If an exception is thrown from a type constructor, the type is not usable in the current application domain. - -✔️ CONSIDER initializing static fields inline rather than explicitly using static constructors, because the runtime is able to optimize the performance of types that don’t have an explicitly defined static constructor. - -*Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - -*Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Member Design Guidelines](member.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/dependency-properties.md b/docs/standard/design-guidelines/dependency-properties.md deleted file mode 100644 index 40348fcf760a8..0000000000000 --- a/docs/standard/design-guidelines/dependency-properties.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -description: "Learn more about: Dependency Properties" -title: "Dependency Properties" -ms.date: "10/22/2008" -ms.assetid: 212cfb1e-cec4-4047-94a6-47209b387f6f ---- -# Dependency Properties - -A dependency property (DP) is a regular property that stores its value in a property store instead of storing it in a type variable (field), for example. - - An attached dependency property is a kind of dependency property modeled as static Get and Set methods representing "properties" describing relationships between objects and their containers (e.g., the position of a `Button` object on a `Panel` container). - - ✔️ DO provide the dependency properties, if you need the properties to support WPF features such as styling, triggers, data binding, animations, dynamic resources, and inheritance. - -## Dependency Property Design - - ✔️ DO inherit from , or one of its subtypes, when implementing dependency properties. The type provides a very efficient implementation of a property store and automatically supports WPF data binding. - - ✔️ DO provide a regular CLR property and public static read-only field storing an instance of for each dependency property. - - ✔️ DO implement dependency properties by calling instance methods and . - - ✔️ DO name the dependency property static field by suffixing the name of the property with "Property." - - ❌ DO NOT set default values of dependency properties explicitly in code; set them in metadata instead. - - If you set a property default explicitly, you might prevent that property from being set by some implicit means, such as a styling. - - ❌ DO NOT put code in the property accessors other than the standard code to access the static field. - - That code won’t execute if the property is set by implicit means, such as a styling, because styling uses the static field directly. - - ❌ DO NOT use dependency properties to store secure data. Even private dependency properties can be accessed publicly. - -## Attached Dependency Property Design - - Dependency properties described in the preceding section represent intrinsic properties of the declaring type; for example, the `Text` property is a property of `TextButton`, which declares it. A special kind of dependency property is the attached dependency property. - - A classic example of an attached property is the property. The property represents Button’s (not Grid’s) column position, but it is only relevant if the Button is contained in a Grid, and so it's "attached" to Buttons by Grids. - -```xaml - - - - - - - - - -``` - - The definition of an attached property looks mostly like that of a regular dependency property, except that the accessors are represented by static Get and Set methods: - -```csharp -public class Grid { - - public static int GetColumn(DependencyObject obj) { - return (int)obj.GetValue(ColumnProperty); - } - - public static void SetColumn(DependencyObject obj, int value) { - obj.SetValue(ColumnProperty,value); - } - - public static readonly DependencyProperty ColumnProperty = - DependencyProperty.RegisterAttached( - "Column", - typeof(int), - typeof(Grid) - ); -} -``` - -## Dependency Property Validation - - Properties often implement what is called validation. Validation logic executes when an attempt is made to change the value of a property. - - Unfortunately dependency property accessors cannot contain arbitrary validation code. Instead, dependency property validation logic needs to be specified during property registration. - - ❌ DO NOT put dependency property validation logic in the property’s accessors. Instead, pass a validation callback to `DependencyProperty.Register` method. - -## Dependency Property Change Notifications - - ❌ DO NOT implement change notification logic in dependency property accessors. Dependency properties have a built-in change notifications feature that must be used by supplying a change notification callback to the . - -## Dependency Property Value Coercion - - Property coercion takes place when the value given to a property setter is modified by the setter before the property store is actually modified. - - ❌ DO NOT implement coercion logic in dependency property accessors. - - Dependency properties have a built-in coercion feature, and it can be used by supplying a coercion callback to the `PropertyMetadata`. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Common Design Patterns](common-design-patterns.md) diff --git a/docs/standard/design-guidelines/designing-for-extensibility.md b/docs/standard/design-guidelines/designing-for-extensibility.md deleted file mode 100644 index e7a71391bc657..0000000000000 --- a/docs/standard/design-guidelines/designing-for-extensibility.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: "Learn more about: Designing for Extensibility" -title: "Designing for Extensibility" -ms.date: "10/22/2008" -helpviewer_keywords: - - "extending class libraries" - - "extensibility with class libraries in .NET Framework" - - "class library design guidelines [.NET Framework], extensibility" - - "class library extensibility [.NET Framework]" -ms.assetid: 1cdb8740-871a-456c-9bd9-db96ca8d79b3 ---- -# Designing for Extensibility - -One important aspect of designing a framework is making sure the extensibility of the framework has been carefully considered. This requires that you understand the costs and benefits associated with various extensibility mechanisms. This chapter helps you decide which of the extensibility mechanisms—subclassing, events, virtual members, callbacks, and so on—can best meet the requirements of your framework. - - There are many ways to allow extensibility in frameworks. They range from less powerful but less costly to very powerful but expensive. For any given extensibility requirement, you should choose the least costly extensibility mechanism that meets the requirements. Keep in mind that it’s usually possible to add more extensibility later, but you can never take it away without introducing breaking changes. - -## In This Section - - [Unsealed Classes](unsealed-classes.md) - [Protected Members](protected-members.md) - [Events and Callbacks](events-and-callbacks.md) - [Virtual Members](virtual-members.md) - [Abstractions (Abstract Types and Interfaces)](abstractions-abstract-types-and-interfaces.md) - [Base Classes for Implementing Abstractions](base-classes-for-implementing-abstractions.md) - [Sealing](sealing.md) - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/enum.md b/docs/standard/design-guidelines/enum.md deleted file mode 100644 index f61f2b0071862..0000000000000 --- a/docs/standard/design-guidelines/enum.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "Enum Design" -description: Design for enums, which are a special kind of value type. Simple enums hold small, closed sets of choices. Flag enums support bitwise operations on enum values. -ms.date: "10/22/2008" -helpviewer_keywords: - - "type design guidelines, enumerations" - - "simple enumerations" - - "enumerations [.NET Framework], design guidelines" - - "class library design guidelines [.NET Framework], enumerations" - - "flags enumerations" -ms.assetid: dd53c952-9d9a-4736-86ff-9540e815d545 ---- -# Enum Design - -Enums are a special kind of value type. There are two kinds of enums: simple enums and flag enums. - -Simple enums represent small closed sets of choices. A common example of the simple enum is a set of colors. - -Flag enums are designed to support bitwise operations on the enum values. A common example of the flags enum is a list of options. - -✔️ DO use an enum to strongly type parameters, properties, and return values that represent sets of values. - -✔️ DO favor using an enum instead of static constants. - -❌ DO NOT use an enum for open sets (such as the operating system version, names of your friends, etc.). - -❌ DO NOT provide reserved enum values that are intended for future use. - -You can always simply add values to the existing enum at a later stage. See [Adding Values to Enums](#add_value) for more details on adding values to enums. Reserved values just pollute the set of real values and tend to lead to user errors. - -❌ AVOID publicly exposing enums with only one value. - -A common practice for ensuring future extensibility of C APIs is to add reserved parameters to method signatures. Such reserved parameters can be expressed as enums with a single default value. This should not be done in managed APIs. Method overloading allows adding parameters in future releases. - -❌ DO NOT include sentinel values in enums. - -Although they are sometimes helpful to framework developers, sentinel values are confusing to users of the framework. They are used to track the state of the enum rather than being one of the values from the set represented by the enum. - -✔️ DO provide a value of zero on simple enums. - -Consider calling the value something like "None." If such a value is not appropriate for this particular enum, the most common default value for the enum should be assigned the underlying value of zero. - -✔️ CONSIDER using (the default in most programming languages) as the underlying type of an enum unless any of the following is true: - -- The enum is a flags enum and you have more than 32 flags, or expect to have more in the future. - -- The underlying type needs to be different than for easier interoperability with unmanaged code expecting different-size enums. - -- A smaller underlying type would result in substantial savings in space. If you expect the enum to be used mainly as an argument for flow of control, the size makes little difference. The size savings might be significant if: - - - You expect the enum to be used as a field in a very frequently instantiated structure or class. - - - You expect users to create large arrays or collections of the enum instances. - - - You expect a large number of instances of the enum to be serialized. - -For in-memory usage, be aware that managed objects are always `DWORD`-aligned, so you effectively need multiple enums or other small structures in an instance to pack a smaller enum with in order to make a difference, because the total instance size is always going to be rounded up to a `DWORD`. - -✔️ DO name flag enums with plural nouns or noun phrases and simple enums with singular nouns or noun phrases. - -❌ DO NOT extend directly. - - is a special type used by the CLR to create user-defined enumerations. Most programming languages provide a programming element that gives you access to this functionality. For example, in C# the `enum` keyword is used to define an enumeration. - - - -### Designing Flag Enums - -✔️ DO apply the to flag enums. Do not apply this attribute to simple enums. - -✔️ DO use powers of two for the flag enum values so they can be freely combined using the bitwise OR operation. - -✔️ CONSIDER providing special enum values for commonly used combinations of flags. - -Bitwise operations are an advanced concept and should not be required for simple tasks. is an example of such a special value. - -❌ AVOID creating flag enums where certain combinations of values are invalid. - -❌ AVOID using flag enum values of zero unless the value represents "all flags are cleared" and is named appropriately, as prescribed by the next guideline. - -✔️ DO name the zero value of flag enums `None`. For a flag enum, the value must always mean "all flags are cleared." - - - -### Adding Value to Enums - -It is very common to discover that you need to add values to an enum after you have already shipped it. There is a potential application compatibility problem when the newly added value is returned from an existing API, because poorly written applications might not handle the new value correctly. - -✔️ CONSIDER adding values to enums, despite a small compatibility risk. - -If you have real data about application incompatibilities caused by additions to an enum, consider adding a new API that returns the new and old values, and deprecate the old API, which should continue returning just the old values. This will ensure that your existing applications remain compatible. - -*Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - -*Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Type Design Guidelines](type.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/equality-operators.md b/docs/standard/design-guidelines/equality-operators.md deleted file mode 100644 index db73469c3f1a3..0000000000000 --- a/docs/standard/design-guidelines/equality-operators.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -description: "Learn more about: Equality Operators" -title: "Equality Operators" -ms.date: "10/22/2008" -helpviewer_keywords: - - "class library design guidelines [.NET Framework], Equals method" - - "class library design guidelines [.NET Framework], equality operator" - - "equality operator (==) [.NET Framework]" - - "Equals method" - - "== operator (equality) [.NET Framework]" -ms.assetid: bc496a91-fefb-4ce0-ab4c-61f09964119a ---- -# Equality Operators - -This section discusses overloading equality operators and refers to `operator==` and `operator!=` as equality operators. - - ❌ DO NOT overload one of the equality operators and not the other. - - ✔️ DO ensure that and the equality operators have exactly the same semantics and similar performance characteristics. - - This often means that `Object.Equals` needs to be overridden when the equality operators are overloaded. - - ❌ AVOID throwing exceptions from equality operators. - - For example, return false if one of the arguments is null instead of throwing `NullReferenceException`. - -## Equality Operators on Value Types - - ✔️ DO overload the equality operators on value types, if equality is meaningful. - - In most programming languages, there is no default implementation of `operator==` for value types. - -## Equality Operators on Reference Types - - ❌ AVOID overloading equality operators on mutable reference types. - - Many languages have built-in equality operators for reference types. The built-in operators usually implement the reference equality, and many developers are surprised when the default behavior is changed to the value equality. - - This problem is mitigated for immutable reference types because immutability makes it much harder to notice the difference between reference equality and value equality. - - ❌ AVOID overloading equality operators on reference types if the implementation would be significantly slower than that of reference equality. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Usage Guidelines](usage-guidelines.md) diff --git a/docs/standard/design-guidelines/event.md b/docs/standard/design-guidelines/event.md deleted file mode 100644 index b15f02e0dc964..0000000000000 --- a/docs/standard/design-guidelines/event.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -description: "Learn more about: Event Design" -title: "Event Design" -ms.date: "10/22/2008" -helpviewer_keywords: - - "pre-events" - - "events [.NET Framework], design guidelines" - - "member design guidelines, events" - - "event handlers [.NET Framework], event design guidelines" - - "post-events" - - "signatures, event handling" -ms.assetid: 67b3c6e2-6a8f-480d-a78f-ebeeaca1b95a ---- -# Event Design - -Events are the most commonly used form of callbacks (constructs that allow the framework to call into user code). Other callback mechanisms include members taking delegates, virtual members, and interface-based plug-ins. Data from usability studies indicate that the majority of developers are more comfortable using events than they are using the other callback mechanisms. Events are nicely integrated with Visual Studio and many languages. - - It is important to note that there are two groups of events: events raised before a state of the system changes, called pre-events, and events raised after a state changes, called post-events. An example of a pre-event would be `Form.Closing`, which is raised before a form is closed. An example of a post-event would be `Form.Closed`, which is raised after a form is closed. - - ✔️ DO use the term "raise" for events rather than "fire" or "trigger." - - ✔️ DO use instead of manually creating new delegates to be used as event handlers. - - ✔️ CONSIDER using a subclass of as the event argument, unless you are absolutely sure the event will never need to carry any data to the event handling method, in which case you can use the `EventArgs` type directly. - - If you ship an API using `EventArgs` directly, you will never be able to add any data to be carried with the event without breaking compatibility. If you use a subclass, even if initially completely empty, you will be able to add properties to the subclass when needed. - - ✔️ DO use a protected virtual method to raise each event. This is only applicable to nonstatic events on unsealed classes, not to structs, sealed classes, or static events. - - The purpose of the method is to provide a way for a derived class to handle the event using an override. Overriding is a more flexible, faster, and more natural way to handle base class events in derived classes. By convention, the name of the method should start with "On" and be followed with the name of the event. - - The derived class can choose not to call the base implementation of the method in its override. Be prepared for this by not including any processing in the method that is required for the base class to work correctly. - - ✔️ DO take one parameter to the protected method that raises an event. - - The parameter should be named `e` and should be typed as the event argument class. - - ❌ DO NOT pass null as the sender when raising a nonstatic event. - - ✔️ DO pass null as the sender when raising a static event. - - ❌ DO NOT pass null as the event data parameter when raising an event. - - You should pass `EventArgs.Empty` if you don’t want to pass any data to the event handling method. Developers expect this parameter not to be null. - - ✔️ CONSIDER raising events that the end user can cancel. This only applies to pre-events. - - Use or its subclass as the event argument to allow the end user to cancel events. - -### Custom Event Handler Design - - There are cases in which `EventHandler` cannot be used, such as when the framework needs to work with earlier versions of the CLR, which did not support Generics. In such cases, you might need to design and develop a custom event handler delegate. - - ✔️ DO use a return type of void for event handlers. - - An event handler can invoke multiple event handling methods, possibly on multiple objects. If event handling methods were allowed to return a value, there would be multiple return values for each event invocation. - - ✔️ DO use `object` as the type of the first parameter of the event handler, and call it `sender`. - - ✔️ DO use or its subclass as the type of the second parameter of the event handler, and call it `e`. - - ❌ DO NOT have more than two parameters on event handlers. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Member Design Guidelines](member.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/events-and-callbacks.md b/docs/standard/design-guidelines/events-and-callbacks.md deleted file mode 100644 index a7f6562869f65..0000000000000 --- a/docs/standard/design-guidelines/events-and-callbacks.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -description: "Learn more about: Events and Callbacks" -title: "Events and Callbacks" -ms.date: "10/22/2008" -helpviewer_keywords: - - "events [.NET Framework], extensibility" - - "methods [.NET Framework], callback" - - "callback methods" - - "callbacks" -ms.assetid: 48b55c60-495f-4089-9396-97f9122bba7c ---- -# Events and Callbacks - -Callbacks are extensibility points that allow a framework to call back into user code through a delegate. These delegates are usually passed to the framework through a parameter of a method. - - Events are a special case of callbacks that supports convenient and consistent syntax for supplying the delegate (an event handler). In addition, Visual Studio's statement completion and designers provide help in using event-based APIs. (See [Event Design](event.md).) - - ✔️ CONSIDER using callbacks to allow users to provide custom code to be executed by the framework. - - ✔️ CONSIDER using events to allow users to customize the behavior of a framework without the need for understanding object-oriented design. - - ✔️ DO prefer events over plain callbacks, because they are more familiar to a broader range of developers and are integrated with Visual Studio statement completion. - - ❌ AVOID using callbacks in performance-sensitive APIs. - - ✔️ DO use the new `Func<...>`, `Action<...>`, or `Expression<...>` types instead of custom delegates, when defining APIs with callbacks. - - `Func<...>` and `Action<...>` represent generic delegates. `Expression<...>` represents function definitions that can be compiled and subsequently invoked at run time but can also be serialized and passed to remote processes. - - ✔️ DO measure and understand performance implications of using `Expression<...>`, instead of using `Func<...>` and `Action<...>` delegates. - - `Expression<...>` types are in most cases logically equivalent to `Func<...>` and `Action<...>` delegates. The main difference between them is that the delegates are intended to be used in local process scenarios; expressions are intended for cases where it's beneficial and possible to evaluate the expression in a remote process or machine. - - ✔️ DO understand that by calling a delegate, you are executing arbitrary code and that could have security, correctness, and compatibility repercussions. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Designing for Extensibility](designing-for-extensibility.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/exception-throwing.md b/docs/standard/design-guidelines/exception-throwing.md deleted file mode 100644 index ce0a9be201877..0000000000000 --- a/docs/standard/design-guidelines/exception-throwing.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -description: "Learn more about: Exception Throwing" -title: "Exception Throwing" -ms.date: "10/22/2008" -helpviewer_keywords: - - "exceptions, throwing" - - "explicitly throwing exceptions" - - "throwing exceptions, design guidelines" -ms.assetid: 5388e02b-52f5-460e-a2b5-eeafe60eeebe ---- -# Exception Throwing - -Exception-throwing guidelines described in this section require a good definition of the meaning of execution failure. Execution failure occurs whenever a member cannot do what it was designed to do (what the member name implies). For example, if the `OpenFile` method cannot return an opened file handle to the caller, it would be considered an execution failure. - - Most developers have become comfortable with using exceptions for usage errors such as division by zero or null references. In the Framework, exceptions are used for all error conditions, including execution errors. - - ❌ DO NOT return error codes. - - Exceptions are the primary means of reporting errors in frameworks. - - ✔️ DO report execution failures by throwing exceptions. - - ✔️ CONSIDER terminating the process by calling `System.Environment.FailFast` (.NET Framework 2.0 feature) instead of throwing an exception if your code encounters a situation where it is unsafe for further execution. - - ❌ DO NOT use exceptions for the normal flow of control, if possible. - - Except for system failures and operations with potential race conditions, framework designers should design APIs so users can write code that does not throw exceptions. For example, you can provide a way to check preconditions before calling a member so users can write code that does not throw exceptions. - - The member used to check preconditions of another member is often referred to as a tester, and the member that actually does the work is called a doer. - - There are cases when the Tester-Doer Pattern can have an unacceptable performance overhead. In such cases, the so-called Try-Parse Pattern should be considered (see [Exceptions and Performance](exceptions-and-performance.md) for more information). - - ✔️ CONSIDER the performance implications of throwing exceptions. Throw rates above 100 per second are likely to noticeably impact the performance of most applications. - - ✔️ DO document all exceptions thrown by publicly callable members because of a violation of the member contract (rather than a system failure) and treat them as part of your contract. - - Exceptions that are a part of the contract should not change from one version to the next (i.e., exception type should not change, and new exceptions should not be added). - - ❌ DO NOT have public members that can either throw or not based on some option. - - ❌ DO NOT have public members that return exceptions as the return value or an `out` parameter. - - Returning exceptions from public APIs instead of throwing them defeats many of the benefits of exception-based error reporting. - - ✔️ CONSIDER using exception builder methods. - - It is common to throw the same exception from different places. To avoid code bloat, use helper methods that create exceptions and initialize their properties. - - Also, members that throw exceptions are not getting inlined. Moving the throw statement inside the builder might allow the member to be inlined. - - ❌ DO NOT throw exceptions from exception filter blocks. - - When an exception filter raises an exception, the exception is caught by the CLR, and the filter returns false. This behavior is indistinguishable from the filter executing and returning false explicitly and is therefore very difficult to debug. - - ❌ AVOID explicitly throwing exceptions from finally blocks. Implicitly thrown exceptions resulting from calling methods that throw are acceptable. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Design Guidelines for Exceptions](exceptions.md) diff --git a/docs/standard/design-guidelines/exceptions-and-performance.md b/docs/standard/design-guidelines/exceptions-and-performance.md deleted file mode 100644 index f11984a1a3904..0000000000000 --- a/docs/standard/design-guidelines/exceptions-and-performance.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -description: "Learn more about: Exceptions and Performance" -title: "Exceptions and Performance" -ms.date: "10/22/2008" -helpviewer_keywords: - - "tester-doer pattern" - - "TryParse pattern" - - "exceptions, throwing" - - "exceptions, performance" - - "throwing exceptions, performance" -ms.assetid: 3ad6aad9-08e6-4232-b336-0e301f2493e6 ---- -# Exceptions and Performance - -One common concern related to exceptions is that if exceptions are used for code that routinely fails, the performance of the implementation will be unacceptable. This is a valid concern. When a member throws an exception, its performance can be orders of magnitude slower. However, it is possible to achieve good performance while strictly adhering to the exception guidelines that disallow using error codes. Two patterns described in this section suggest ways to do this. - - ❌ DO NOT use error codes because of concerns that exceptions might affect performance negatively. - - To improve performance, it is possible to use either the Tester-Doer Pattern or the Try-Parse Pattern, described in the next two sections. - -## Tester-Doer Pattern - - Sometimes performance of an exception-throwing member can be improved by breaking the member into two. Let’s look at the method of the interface. - -```csharp -ICollection numbers = ... -numbers.Add(1); -``` - - The method `Add` throws if the collection is read-only. This can be a performance problem in scenarios where the method call is expected to fail often. One of the ways to mitigate the problem is to test whether the collection is writable before trying to add a value. - -```csharp -ICollection numbers = ... -... -if (!numbers.IsReadOnly) -{ - numbers.Add(1); -} -``` - - The member used to test a condition, which in our example is the property `IsReadOnly`, is referred to as the tester. The member used to perform a potentially throwing operation, the `Add` method in our example, is referred to as the doer. - - ✔️ CONSIDER the Tester-Doer Pattern for members that might throw exceptions in common scenarios to avoid performance problems related to exceptions. - -## Try-Parse Pattern - - For extremely performance-sensitive APIs, an even faster pattern than the Tester-Doer Pattern described in the previous section should be used. The pattern calls for adjusting the member name to make a well-defined test case a part of the member semantics. For example, defines a method that throws an exception if parsing of a string fails. It also defines a corresponding method that attempts to parse, but returns false if parsing is unsuccessful and returns the result of a successful parsing using an `out` parameter. - -```csharp -public struct DateTime -{ - public static DateTime Parse(string dateTime) - { - ... - } - public static bool TryParse(string dateTime, out DateTime result) - { - ... - } -} -``` - - When using this pattern, it is important to define the try functionality in strict terms. If the member fails for any reason other than the well-defined try, the member must still throw a corresponding exception. - - ✔️ CONSIDER the Try-Parse Pattern for members that might throw exceptions in common scenarios to avoid performance problems related to exceptions. - - ✔️ DO use the prefix "Try" and Boolean return type for methods implementing this pattern. - - ✔️ DO provide an exception-throwing member for each member using the Try-Parse Pattern. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Design Guidelines for Exceptions](exceptions.md) diff --git a/docs/standard/design-guidelines/exceptions.md b/docs/standard/design-guidelines/exceptions.md deleted file mode 100644 index 259a7eb7f43fe..0000000000000 --- a/docs/standard/design-guidelines/exceptions.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: "Learn more about: Design Guidelines for Exceptions" -title: "Design Guidelines for Exceptions" -ms.date: "10/22/2008" -helpviewer_keywords: - - "exceptions [.NET Framework], design guidelines" - - "class library design guidelines [.NET Framework], exceptions" - - "errors [.NET Framework], exceptions" - - "reporting errors" -ms.assetid: bc177b2f-7528-4ae4-83db-aacfb04b86d0 ---- -# Design Guidelines for Exceptions - -Exception handling has many advantages over return-value-based error reporting. Good framework design helps the application developer realize the benefits of exceptions. This section discusses the benefits of exceptions and presents guidelines for using them effectively. - -## In This Section - - [Exception Throwing](exception-throwing.md) - [Using Standard Exception Types](using-standard-exception-types.md) - [Exceptions and Performance](exceptions-and-performance.md) - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/extension-methods.md b/docs/standard/design-guidelines/extension-methods.md deleted file mode 100644 index e0d4592b0c57e..0000000000000 --- a/docs/standard/design-guidelines/extension-methods.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -description: "Learn more about: Extension Methods" -title: "Extension Methods" -ms.date: "10/22/2008" -ms.assetid: 5de945cb-88f4-49d7-b0e6-f098300cf357 ---- -# Extension Methods - -Extension methods are a language feature that allows static methods to be called using instance method call syntax. These methods must take at least one parameter, which represents the instance the method is to operate on. - - The class that defines such extension methods is referred to as the "sponsor" class, and it must be declared as static. To use extension methods, one must import the namespace defining the sponsor class. - - ❌ AVOID frivolously defining extension methods, especially on types you don't own. - - If you do own source code of a type, consider using regular instance methods instead. If you don't own, and you want to add a method, be very careful. Liberal use of extension methods has the potential of cluttering APIs of types that were not designed to have these methods. - - ✔️ CONSIDER using extension methods in any of the following scenarios: - -- To provide helper functionality relevant to every implementation of an interface, if said functionality can be written in terms of the core interface. This is because concrete implementations cannot otherwise be assigned to interfaces. For example, the `LINQ to Objects` operators are implemented as extension methods for all types. Thus, any `IEnumerable<>` implementation is automatically LINQ-enabled. - -- When an instance method would introduce a dependency on some type, but such a dependency would break dependency management rules. For example, a dependency from to is probably not desirable, and so `String.ToUri()` instance method returning `System.Uri` would be the wrong design from a dependency management perspective. A static extension method `Uri.ToUri(this string str)` returning `System.Uri` would be a much better design. - - ❌ AVOID defining extension methods on . - - VB users will not be able to call such methods on object references using the extension method syntax. VB does not support calling such methods because, in VB, declaring a reference as Object forces all method invocations on it to be late bound (actual member called is determined at run time), while bindings to extension methods are determined at compile-time (early bound). - - Note that the guideline applies to other languages where the same binding behavior is present, or where extension methods are not supported. - - ❌ DO NOT put extension methods in the same namespace as the extended type unless it is for adding methods to interfaces or for dependency management. - - ❌ AVOID defining two or more extension methods with the same signature, even if they reside in different namespaces. - - ✔️ CONSIDER defining extension methods in the same namespace as the extended type if the type is an interface and if the extension methods are meant to be used in most or all cases. - - ❌ DO NOT define extension methods implementing a feature in namespaces normally associated with other features. Instead, define them in the namespace associated with the feature they belong to. - - ❌ AVOID generic naming of namespaces dedicated to extension methods (e.g., "Extensions"). Use a descriptive name (e.g., "Routing") instead. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Member Design Guidelines](member.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/field.md b/docs/standard/design-guidelines/field.md deleted file mode 100644 index 540d428e559f0..0000000000000 --- a/docs/standard/design-guidelines/field.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -description: "Learn more about: Field Design" -title: "Field Design" -ms.date: "10/22/2008" -helpviewer_keywords: - - "fields, design guidelines" - - "read-only fields" - - "member design guidelines, fields" -ms.assetid: 7cb4b0f3-7a10-4c93-b84d-733f7134fcf8 ---- -# Field Design - -The principle of encapsulation is one of the most important notions in object-oriented design. This principle states that data stored inside an object should be accessible only to that object. - - A useful way to interpret the principle is to say that a type should be designed so that changes to fields of that type (name or type changes) can be made without breaking code other than for members of the type. This interpretation immediately implies that all fields must be private. - - We exclude constant and static read-only fields from this strict restriction, because such fields, almost by definition, are never required to change. - - ❌ DO NOT provide instance fields that are public or protected. - - You should provide properties for accessing fields instead of making them public or protected. - - ✔️ DO use constant fields for constants that will never change. - - The compiler burns the values of const fields directly into calling code. Therefore, const values can never be changed without the risk of breaking compatibility. - - ✔️ DO use public static `readonly` fields for predefined object instances. - - If there are predefined instances of the type, declare them as public read-only static fields of the type itself. - - ❌ DO NOT assign instances of mutable types to `readonly` fields. - - A mutable type is a type with instances that can be modified after they are instantiated. For example, arrays, most collections, and streams are mutable types, but , , and are all immutable. The read-only modifier on a reference type field prevents the instance stored in the field from being replaced, but it does not prevent the field’s instance data from being modified by calling members changing the instance. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Member Design Guidelines](member.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/general-naming-conventions.md b/docs/standard/design-guidelines/general-naming-conventions.md deleted file mode 100644 index 85f2b9358c6aa..0000000000000 --- a/docs/standard/design-guidelines/general-naming-conventions.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "General Naming Conventions" -description: Use general naming conventions relating to word choice, guidelines on using abbreviations and acronyms, and guidance on avoiding language-specific names. -ms.date: "10/22/2008" -helpviewer_keywords: - - "names [.NET Framework], conflicts" - - "type names, conflicts" - - "language-specific type names" - - "names [.NET Framework], about naming guidelines" - - "names [.NET Framework], abbreviations" - - "abbreviation naming guidelines" - - "acronym naming guidelines" - - "Hungarian notation" - - "names [.NET Framework], type names" - - "names [.NET Framework], acronyms" -ms.topic: reference ---- -# General Naming Conventions - -This section describes general naming conventions that relate to word choice, guidelines on using abbreviations and acronyms, and recommendations on how to avoid using language-specific names. - -## Word Choice - - ✔️ DO choose easily readable identifier names. - - For example, a property named `HorizontalAlignment` is more English-readable than `AlignmentHorizontal`. - - ✔️ DO favor readability over brevity. - - The property name `CanScrollHorizontally` is better than `ScrollableX` (an obscure reference to the X-axis). - - ❌ DO NOT use underscores, hyphens, or any other nonalphanumeric characters. - - ❌ DO NOT use Hungarian notation. - - ❌ AVOID using identifiers that conflict with keywords of widely used programming languages. - - According to Rule 4 of the Common Language Specification (CLS), all compliant languages must provide a mechanism that allows access to named items that use a keyword of that language as an identifier. C#, for example, uses the @ sign as an escape mechanism in this case. However, it is still a good idea to avoid common keywords because it is much more difficult to use a method with the escape sequence than one without it. - -## Using Abbreviations and Acronyms - - ❌ DO NOT use abbreviations or contractions as part of identifier names. - - For example, use `GetWindow` rather than `GetWin`. - - ❌ DO NOT use any acronyms that are not widely accepted, and even if they are, only when necessary. - -## Avoiding Language-Specific Names - - ✔️ DO use semantically interesting names rather than language-specific keywords for type names. - - For example, `GetLength` is a better name than `GetInt`. - - ✔️ DO use a generic CLR type name, rather than a language-specific name, in the rare cases when an identifier has no semantic meaning beyond its type. - - For example, a method converting to should be named `ToInt64`, not `ToLong` (because is a CLR name for the C#-specific alias `long`). The following table presents several base data types using the CLR type names (as well as the corresponding type names for C#, Visual Basic, and C++). - -|C#|Visual Basic|C++|CLR| -|---------|------------------|-----------|---------| -|**sbyte**|**SByte**|**char**|**SByte**| -|**byte**|**Byte**|**unsigned char**|**Byte**| -|**short**|**Short**|**short**|**Int16**| -|**ushort**|**UInt16**|**unsigned short**|**UInt16**| -|**int**|**Integer**|**int**|**Int32**| -|**uint**|**UInt32**|**unsigned int**|**UInt32**| -|**long**|**Long**|**__int64**|**Int64**| -|**ulong**|**UInt64**|**unsigned __int64**|**UInt64**| -|**float**|**Single**|**float**|**Single**| -|**double**|**Double**|**double**|**Double**| -|**bool**|**Boolean**|**bool**|**Boolean**| -|**char**|**Char**|**wchar_t**|**Char**| -|**string**|**String**|**String**|**String**| -|**object**|**Object**|**Object**|**Object**| - - ✔️ DO use a common name, such as `value` or `item`, rather than repeating the type name, in the rare cases when an identifier has no semantic meaning and the type of the parameter is not important. - -## Naming New Versions of Existing APIs - - ✔️ DO use a name similar to the old API when creating new versions of an existing API. - - This helps to highlight the relationship between the APIs. - - ✔️ DO prefer adding a suffix rather than a prefix to indicate a new version of an existing API. - - This will assist discovery when browsing documentation, or using IntelliSense. The old version of the API will be organized close to the new APIs, because most browsers and IntelliSense show identifiers in alphabetical order. - - ✔️ CONSIDER using a brand new, but meaningful identifier, instead of adding a suffix or a prefix. - - ✔️ DO use a numeric suffix to indicate a new version of an existing API, particularly if the existing name of the API is the only name that makes sense (i.e., if it is an industry standard) and if adding any meaningful suffix (or changing the name) is not an appropriate option. - - ❌ DO NOT use the "Ex" (or a similar) suffix for an identifier to distinguish it from an earlier version of the same API. - - ✔️ DO use the "64" suffix when introducing versions of APIs that operate on a 64-bit integer (a long integer) instead of a 32-bit integer. You only need to take this approach when the existing 32-bit API exists; don't do it for brand new APIs with only a 64-bit version. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework design guidelines](index.md) -- [Naming guidelines](naming-guidelines.md) -- [.NET naming conventions for EditorConfig](/visualstudio/ide/editorconfig-naming-conventions) diff --git a/docs/standard/design-guidelines/guidelines-for-collections.md b/docs/standard/design-guidelines/guidelines-for-collections.md deleted file mode 100644 index aed3935eedbbd..0000000000000 --- a/docs/standard/design-guidelines/guidelines-for-collections.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -description: "Learn more about: Guidelines for Collections" -title: "Guidelines for Collections" -ms.date: "10/22/2008" -ms.assetid: 297b8f1d-b11f-4dc6-960a-8e990817304e ---- -# Guidelines for Collections - -Any type designed specifically to manipulate a group of objects having some common characteristic can be considered a collection. It is almost always appropriate for such types to implement or , so in this section we only consider types implementing one or both of those interfaces to be collections. - - ❌ DO NOT use weakly typed collections in public APIs. - - The type of all return values and parameters representing collection items should be the exact item type, not any of its base types (this applies only to public members of the collection). - - ❌ DO NOT use or in public APIs. - - These types are data structures designed to be used in internal implementation, not in public APIs. `List` is optimized for performance and power at the cost of cleanness of the APIs and flexibility. For example, if you return `List`, you will not ever be able to receive notifications when client code modifies the collection. Also, `List` exposes many members, such as , that are not useful or applicable in many scenarios. The following two sections describe types (abstractions) designed specifically for use in public APIs. - - ❌ DO NOT use `Hashtable` or `Dictionary` in public APIs. - - These types are data structures designed to be used in internal implementation. Public APIs should use , `IDictionary `, or a custom type implementing one or both of the interfaces. - - ❌ DO NOT use , , or any other type that implements either of these interfaces, except as the return type of a `GetEnumerator` method. - - Types returning enumerators from methods other than `GetEnumerator` cannot be used with the `foreach` statement. - - ❌ DO NOT implement both `IEnumerator` and `IEnumerable` on the same type. The same applies to the nongeneric interfaces `IEnumerator` and `IEnumerable`. - -## Collection Parameters - - ✔️ DO use the least-specialized type possible as a parameter type. Most members taking collections as parameters use the `IEnumerable` interface. - - ❌ AVOID using or as a parameter just to access the `Count` property. - - Instead, consider using `IEnumerable` or `IEnumerable` and dynamically checking whether the object implements `ICollection` or `ICollection`. - -## Collection Properties and Return Values - - ❌ DO NOT provide settable collection properties. - - Users can replace the contents of the collection by clearing the collection first and then adding the new contents. If replacing the whole collection is a common scenario, consider providing the `AddRange` method on the collection. - - ✔️ DO use `Collection` or a subclass of `Collection` for properties or return values representing read/write collections. - - If `Collection` does not meet some requirement (e.g., the collection must not implement ), use a custom collection by implementing `IEnumerable`, `ICollection`, or . - - ✔️ DO use , a subclass of `ReadOnlyCollection`, or in rare cases `IEnumerable` for properties or return values representing read-only collections. - - In general, prefer `ReadOnlyCollection`. If it does not meet some requirement (e.g., the collection must not implement `IList`), use a custom collection by implementing `IEnumerable`, `ICollection`, or `IList`. If you do implement a custom read-only collection, implement `ICollection.IsReadOnly` to return `true`. - - In cases where you are sure that the only scenario you will ever want to support is forward-only iteration, you can simply use `IEnumerable`. - - ✔️ CONSIDER using subclasses of generic base collections instead of using the collections directly. - - This allows for a better name and for adding helper members that are not present on the base collection types. This is especially applicable to high-level APIs. - - ✔️ CONSIDER returning a subclass of `Collection` or `ReadOnlyCollection` from very commonly used methods and properties. - - This will make it possible for you to add helper methods or change the collection implementation in the future. - - ✔️ CONSIDER using a keyed collection if the items stored in the collection have unique keys (names, IDs, etc.). Keyed collections are collections that can be indexed by both an integer and a key and are usually implemented by inheriting from `KeyedCollection`. - - Keyed collections usually have larger memory footprints and should not be used if the memory overhead outweighs the benefits of having the keys. - - ❌ DO NOT return null values from collection properties or from methods returning collections. Return an empty collection or an empty array instead. - - The general rule is that null and empty (0 item) collections or arrays should be treated the same. - -### Snapshots Versus Live Collections - - Collections representing a state at some point in time are called snapshot collections. For example, a collection containing rows returned from a database query would be a snapshot. Collections that always represent the current state are called live collections. For example, a collection of `ComboBox` items is a live collection. - - ❌ DO NOT return snapshot collections from properties. Properties should return live collections. - - Property getters should be very lightweight operations. Returning a snapshot requires creating a copy of an internal collection in an O(n) operation. - - ✔️ DO use either a snapshot collection or a live `IEnumerable` (or its subtype) to represent collections that are volatile (i.e., that can change without explicitly modifying the collection). - - In general, all collections representing a shared resource (e.g., files in a directory) are volatile. Such collections are very difficult or impossible to implement as live collections unless the implementation is simply a forward-only enumerator. - -## Choosing Between Arrays and Collections - - ✔️ DO prefer collections over arrays. - - Collections provide more control over contents, can evolve over time, and are more usable. In addition, using arrays for read-only scenarios is discouraged because the cost of cloning the array is prohibitive. Usability studies have shown that some developers feel more comfortable using collection-based APIs. - - However, if you are developing low-level APIs, it might be better to use arrays for read-write scenarios. Arrays have a smaller memory footprint, which helps reduce the working set, and access to elements in an array is faster because it is optimized by the runtime. - - ✔️ CONSIDER using arrays in low-level APIs to minimize memory consumption and maximize performance. - - ✔️ DO use byte arrays instead of collections of bytes. - - ❌ DO NOT use arrays for properties if the property would have to return a new array (e.g., a copy of an internal array) every time the property getter is called. - -## Implementing Custom Collections - - ✔️ CONSIDER inheriting from `Collection`, `ReadOnlyCollection`, or `KeyedCollection` when designing new collections. - - ✔️ DO implement `IEnumerable` when designing new collections. Consider implementing `ICollection` or even `IList` where it makes sense. - - When implementing such custom collection, follow the API pattern established by `Collection` and `ReadOnlyCollection` as closely as possible. That is, implement the same members explicitly, name the parameters like these two collections name them, and so on. - - ✔️ CONSIDER implementing nongeneric collection interfaces (`IList` and `ICollection`) if the collection will often be passed to APIs taking these interfaces as input. - - ❌ AVOID implementing collection interfaces on types with complex APIs unrelated to the concept of a collection. - - ❌ DO NOT inherit from nongeneric base collections such as `CollectionBase`. Use `Collection`, `ReadOnlyCollection`, and `KeyedCollection` instead. - -### Naming Custom Collections - - Collections (types that implement `IEnumerable`) are created mainly for two reasons: (1) to create a new data structure with structure-specific operations and often different performance characteristics than existing data structures (e.g., , , ), and (2) to create a specialized collection for holding a specific set of items (e.g., ). Data structures are most often used in the internal implementation of applications and libraries. Specialized collections are mainly to be exposed in APIs (as property and parameter types). - - ✔️ DO use the "Dictionary" suffix in names of abstractions implementing `IDictionary` or `IDictionary`. - - ✔️ DO use the "Collection" suffix in names of types implementing `IEnumerable` (or any of its descendants) and representing a list of items. - - ✔️ DO use the appropriate data structure name for custom data structures. - - ❌ AVOID using any suffixes implying particular implementation, such as "LinkedList" or "Hashtable," in names of collection abstractions. - - ✔️ CONSIDER prefixing collection names with the name of the item type. For example, a collection storing items of type `Address` (implementing `IEnumerable
`) should be named `AddressCollection`. If the item type is an interface, the "I" prefix of the item type can be omitted. Thus, a collection of items can be called `DisposableCollection`. - - ✔️ CONSIDER using the "ReadOnly" prefix in names of read-only collections if a corresponding writeable collection might be added or already exists in the framework. - - For example, a read-only collection of strings should be called `ReadOnlyStringCollection`. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Usage Guidelines](usage-guidelines.md) diff --git a/docs/standard/design-guidelines/index.md b/docs/standard/design-guidelines/index.md deleted file mode 100644 index 8edea3c501b2d..0000000000000 --- a/docs/standard/design-guidelines/index.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "Framework Design Guidelines" -description: See framework design guidelines for designing libraries that extend and interact with .NET, to ensure API consistency and ease of use. -titleSuffix: "" -ms.date: "10/22/2008" -helpviewer_keywords: - - "libraries, .NET Framework class library" - - "class library design guidelines [.NET Framework], about" - - "class library design guidelines [.NET Framework]" -ms.assetid: 5fbcaf4f-ea2a-4d20-b0d6-e61dee202b4b ---- -# Framework Design Guidelines - -This section provides guidelines for designing libraries that extend and interact with the .NET Framework. The goal is to help library designers ensure API consistency and ease of use by providing a unified programming model that is independent of the programming language used for development. We recommend that you follow these design guidelines when developing classes and components that extend the .NET Framework. Inconsistent library design adversely affects developer productivity and discourages adoption. - - The guidelines are organized as simple recommendations prefixed with the terms `Do`, `Consider`, `Avoid`, and `Do not`. These guidelines are intended to help class library designers understand the trade-offs between different solutions. There might be situations where good library design requires that you violate these design guidelines. Such cases should be rare, and it is important that you have a clear and compelling reason for your decision. - - These guidelines are excerpted from the book *Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition*, by Krzysztof Cwalina and Brad Abrams. - -## In This Section - - [Naming Guidelines](naming-guidelines.md) - Provides guidelines for naming assemblies, namespaces, types, and members in class libraries. - - [Type Design Guidelines](type.md) - Provides guidelines for using static and abstract classes, interfaces, enumerations, structures, and other types. - - [Member Design Guidelines](member.md) - Provides guidelines for designing and using properties, methods, constructors, fields, events, operators, and parameters. - - [Designing for Extensibility](designing-for-extensibility.md) - Discusses extensibility mechanisms such as subclassing, using events, virtual members, and callbacks, and explains how to choose the mechanisms that best meet your framework's requirements. - - [Design Guidelines for Exceptions](exceptions.md) - Describes design guidelines for designing, throwing, and catching exceptions. - - [Usage Guidelines](usage-guidelines.md) - Describes guidelines for using common types such as arrays, attributes, and collections, supporting serialization, and overloading equality operators. - - [Common Design Patterns](common-design-patterns.md) - Provides guidelines for choosing and implementing dependency properties. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Overview](../../framework/get-started/overview.md) -- [Development Guide](../../framework/development-guide.md) diff --git a/docs/standard/design-guidelines/interface.md b/docs/standard/design-guidelines/interface.md deleted file mode 100644 index af14002c062bd..0000000000000 --- a/docs/standard/design-guidelines/interface.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -description: "Learn more about: Interface Design" -title: "Interface Design" -ms.date: "10/22/2008" -helpviewer_keywords: - - "interfaces [.NET Framework], design guidelines" - - "type design guidelines, interfaces" - - "class library design guidelines [.NET Framework], interfaces" -ms.assetid: a016bd18-6710-4358-9438-9f190a295392 ---- -# Interface Design - -Although most APIs are best modeled using classes and structs, there are cases in which interfaces are more appropriate or are the only option. - - The CLR does not support multiple inheritance (i.e., CLR classes cannot inherit from more than one base class), but it does allow types to implement one or more interfaces in addition to inheriting from a base class. Therefore, interfaces are often used to achieve the effect of multiple inheritance. For example, is an interface that allows types to support disposability independent of any other inheritance hierarchy in which they want to participate. - - The other situation in which defining an interface is appropriate is in creating a common interface that can be supported by several types, including some value types. Value types cannot inherit from types other than , but they can implement interfaces, so using an interface is the only option in order to provide a common base type. - - ✔️ DO define an interface if you need some common API to be supported by a set of types that includes value types. - - ✔️ CONSIDER defining an interface if you need to support its functionality on types that already inherit from some other type. - - ❌ AVOID using marker interfaces (interfaces with no members). - - If you need to mark a class as having a specific characteristic (marker), in general, use a custom attribute rather than an interface. - - ✔️ DO provide at least one type that is an implementation of an interface. - - Doing this helps to validate the design of the interface. For example, is an implementation of the interface. - - ✔️ DO provide at least one API that consumes each interface you define (a method taking the interface as a parameter or a property typed as the interface). - - Doing this helps to validate the interface design. For example, consumes the interface. - - ❌ DO NOT add members to an interface that has previously shipped. - - Doing so would break implementations of the interface. You should create a new interface in order to avoid versioning problems. - - Except for the situations described in these guidelines, you should, in general, choose classes rather than interfaces in designing managed code reusable libraries. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Type Design Guidelines](type.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/member-overloading.md b/docs/standard/design-guidelines/member-overloading.md deleted file mode 100644 index a5c9ad66ccd12..0000000000000 --- a/docs/standard/design-guidelines/member-overloading.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -description: "Learn more about: Member Overloading" -title: "Member Overloading" -ms.date: "10/22/2008" -helpviewer_keywords: - - "default arguments" - - "members [.NET Framework], overloaded" - - "member design guidelines [.NET Framework], overloading" - - "overloaded members" - - "signatures, members" -ms.assetid: 964ba19e-8b94-4b5b-b1e3-5a0b531a0bb1 ---- -# Member Overloading - -Member overloading means creating two or more members on the same type that differ only in the number or type of parameters but have the same name. For example, in the following, the `WriteLine` method is overloaded: - -```csharp -public static class Console { - public void WriteLine(); - public void WriteLine(string value); - public void WriteLine(bool value); - ... -} -``` - - Because only methods, constructors, and indexed properties can have parameters, only those members can be overloaded. - - Overloading is one of the most important techniques for improving usability, productivity, and readability of reusable libraries. Overloading on the number of parameters makes it possible to provide simpler versions of constructors and methods. Overloading on the parameter type makes it possible to use the same member name for members performing identical operations on a selected set of different types. - - ✔️ DO try to use descriptive parameter names to indicate the default used by shorter overloads. - - ❌ AVOID arbitrarily varying parameter names in overloads. If a parameter in one overload represents the same input as a parameter in another overload, the parameters should have the same name. - - ❌ AVOID being inconsistent in the ordering of parameters in overloaded members. Parameters with the same name should appear in the same position in all overloads. - - ✔️ DO make only the longest overload virtual (if extensibility is required). Shorter overloads should simply call through to a longer overload. - - ❌ DO NOT use `ref` or `out` modifiers to overload members. - - Some languages cannot resolve calls to overloads like this. In addition, such overloads usually have completely different semantics and probably should not be overloads but two separate methods instead. - - ❌ DO NOT have overloads with parameters at the same position and similar types yet with different semantics. - - ✔️ DO allow `null` to be passed for optional arguments. - - ✔️ DO use member overloading rather than defining members with default arguments. - - Default arguments are not CLS compliant. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Member Design Guidelines](member.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/member.md b/docs/standard/design-guidelines/member.md deleted file mode 100644 index 92d574bdc3c3c..0000000000000 --- a/docs/standard/design-guidelines/member.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "Member Design Guidelines" -description: Learn member design guidelines in .NET. Members include methods, properties, events, constructors, and fields. -ms.date: "10/22/2008" -helpviewer_keywords: - - "member design guidelines [.NET Framework], about member design guidelines" - - "members [.NET Framework], design guidelines" - - "class library design guidelines [.NET Framework], members" - - "member design guidelines [.NET Framework]" -ms.assetid: 0ce93180-1d7b-4f8c-9306-f828b2d66b8f ---- -# Member Design Guidelines - -Methods, properties, events, constructors, and fields are collectively referred to as members. Members are ultimately the means by which framework functionality is exposed to the end users of a framework. - - Members can be virtual or nonvirtual, concrete or abstract, static or instance, and can have several different scopes of accessibility. All this variety provides incredible expressiveness but at the same time requires care on the part of the framework designer. - - This chapter offers basic guidelines that should be followed when designing members of any type. - -## In This Section - - [Member Overloading](member-overloading.md) - [Property Design](property.md) - [Constructor Design](constructor.md) - [Event Design](event.md) - [Field Design](field.md) - [Extension Methods](extension-methods.md) - [Operator Overloads](operator-overloads.md) - [Parameter Design](parameter-design.md) - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/names-of-assemblies-and-dlls.md b/docs/standard/design-guidelines/names-of-assemblies-and-dlls.md deleted file mode 100644 index e2693c1f24662..0000000000000 --- a/docs/standard/design-guidelines/names-of-assemblies-and-dlls.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "Names of Assemblies and DLLs" -description: Learn guidelines for naming assemblies and dynamic-link libraries (DLLs). An assembly can span one or more files, but it usually maps one-to-one with a DLL. -ms.date: "10/22/2008" -helpviewer_keywords: - - "names [.NET Framework], DLLs" - - "names [.NET Framework], assemblies" - - "assemblies [.NET Framework], names" - - "DLLs, names" -ms.assetid: e800b610-31b4-4949-9c14-cb60e9f254be ---- -# Names of Assemblies and DLLs - -An assembly is the unit of deployment and identity for managed code programs. Although assemblies can span one or more files, typically an assembly maps one-to-one with a DLL. Therefore, this section describes only DLL naming conventions, which then can be mapped to assembly naming conventions. - - ✔️ DO choose names for your assembly DLLs that suggest large chunks of functionality, such as System.Data. - - Assembly and DLL names don’t have to correspond to namespace names, but it is reasonable to follow the namespace name when naming assemblies. A good rule of thumb is to name the DLL based on the common prefix of the namespaces contained in the assembly. For example, an assembly with two namespaces, `MyCompany.MyTechnology.FirstFeature` and `MyCompany.MyTechnology.SecondFeature`, could be called `MyCompany.MyTechnology.dll`. - - ✔️ CONSIDER naming DLLs according to the following pattern: - - `..dll` - - where `` contains one or more dot-separated clauses. For example: - - `Litware.Controls.dll`. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Naming Guidelines](naming-guidelines.md) diff --git a/docs/standard/design-guidelines/names-of-classes-structs-and-interfaces.md b/docs/standard/design-guidelines/names-of-classes-structs-and-interfaces.md deleted file mode 100644 index 2cfaab3c1ed63..0000000000000 --- a/docs/standard/design-guidelines/names-of-classes-structs-and-interfaces.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: "Names of Classes, Structs, and Interfaces" -description: Use these guidelines for naming Classes, Structs, and Interfaces as part of guidelines for designing libraries that extend and interact .NET libraries. -ms.date: "10/22/2008" -helpviewer_keywords: - - "type names, guidelines" - - "classes [.NET Framework], names" - - "enumerations [.NET Framework], names" - - "names [.NET Framework], interfaces" - - "common type names" - - "names [.NET Framework], type names" - - "names [.NET Framework], classes" - - "interfaces [.NET Framework], names" - - "generic type parameters" -ms.assetid: 87a4b0da-ed64-43b1-ac43-968576c444ce ---- -# Names of Classes, Structs, and Interfaces - -The naming guidelines that follow apply to general type naming. - - ✔️ DO name classes and structs with nouns or noun phrases, using PascalCasing. - - This distinguishes type names from methods, which are named with verb phrases. - - ✔️ DO name interfaces with adjective phrases, or occasionally with nouns or noun phrases. - - Nouns and noun phrases should be used rarely and they might indicate that the type should be an abstract class, and not an interface. - - ❌ DO NOT give class names a prefix (e.g., "C"). - - ✔️ CONSIDER ending the name of derived classes with the name of the base class. - - This is very readable and explains the relationship clearly. Some examples of this in code are: `ArgumentOutOfRangeException`, which is a kind of `Exception`, and `SerializableAttribute`, which is a kind of `Attribute`. However, it is important to use reasonable judgment in applying this guideline; for example, the `Button` class is a kind of `Control` event, although `Control` doesn’t appear in its name. - - ✔️ DO prefix interface names with the letter I, to indicate that the type is an interface. - - For example, `IComponent` (descriptive noun), `ICustomAttributeProvider` (noun phrase), and `IPersistable` (adjective) are appropriate interface names. As with other type names, avoid abbreviations. - - ✔️ DO ensure that the names differ only by the "I" prefix on the interface name when you are defining a class–interface pair where the class is a standard implementation of the interface. - -## Names of Generic Type Parameters - - Generics were added to .NET Framework 2.0. The feature introduced a new kind of identifier called *type parameter*. - - ✔️ DO name generic type parameters with descriptive names unless a single-letter name is completely self-explanatory and a descriptive name would not add value. - - ✔️ CONSIDER using `T` as the type parameter name for types with one single-letter type parameter. - -```csharp -public int IComparer { ... } -public delegate bool Predicate(T item); -public struct Nullable where T:struct { ... } -``` - - ✔️ DO prefix descriptive type parameter names with `T`. - -```csharp -public interface ISessionChannel where TSession : ISession { - TSession Session { get; } -} -``` - - ✔️ CONSIDER indicating constraints placed on a type parameter in the name of the parameter. - - For example, a parameter constrained to `ISession` might be called `TSession`. - -## Names of Common Types - - ✔️ DO follow the guidelines described in the following table when naming types derived from or implementing certain .NET Framework types. - -|Base Type|Derived/Implementing Type Guideline| -|---------------|------------------------------------------| -|`System.Attribute`|✔️ DO add the suffix "Attribute" to names of custom attribute classes.| -|`System.Delegate`|✔️ DO add the suffix "EventHandler" to names of delegates that are used in events.

✔️ DO add the suffix "Callback" to names of delegates other than those used as event handlers.

❌ DO NOT add the suffix "Delegate" to a delegate.| -|`System.EventArgs`|✔️ DO add the suffix "EventArgs."| -|`System.Enum`|❌ DO NOT derive from this class; use the keyword supported by your language instead; for example, in C#, use the `enum` keyword.

❌ DO NOT add the suffix "Enum" or "Flag."| -|`System.Exception`|✔️ DO add the suffix "Exception."| -|`IDictionary`
`IDictionary`|✔️ DO add the suffix "Dictionary." Note that `IDictionary` is a specific type of collection, but this guideline takes precedence over the more general collections guideline that follows.| -|`IEnumerable`
`ICollection`
`IList`
`IEnumerable`
`ICollection`
`IList`|✔️ DO add the suffix "Collection."| -|`System.IO.Stream`|✔️ DO add the suffix "Stream."| -|`CodeAccessPermission IPermission`|✔️ DO add the suffix "Permission."| - -## Naming Enumerations - - Names of enumeration types (also called enums) in general should follow the standard type-naming rules (PascalCasing, etc.). However, there are additional guidelines that apply specifically to enums. - - ✔️ DO use a singular type name for an enumeration unless its values are bit fields. - - ✔️ DO use a plural type name for an enumeration with bit fields as values, also called flags enum. - - ❌ DO NOT use an "Enum" suffix in enum type names. - - ❌ DO NOT use "Flag" or "Flags" suffixes in enum type names. - - ❌ DO NOT use a prefix on enumeration value names (e.g., "ad" for ADO enums, "rtf" for rich text enums, etc.). - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Naming Guidelines](naming-guidelines.md) diff --git a/docs/standard/design-guidelines/names-of-namespaces.md b/docs/standard/design-guidelines/names-of-namespaces.md deleted file mode 100644 index 47bb9983e39ac..0000000000000 --- a/docs/standard/design-guidelines/names-of-namespaces.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "Names of Namespaces" -description: Use these guidelines for naming namespaces as part of guidelines for designing libraries that extend and interact with .NET libraries. -ms.date: "10/22/2008" -helpviewer_keywords: - - "names [.NET Framework], conflicts" - - "names [.NET Framework], namespaces" - - "type names, conflicts" - - "namespaces [.NET Framework], names" - - "names [.NET Framework], type names" -ms.assetid: a49058d2-0276-43a7-9502-04adddf857b2 ---- -# Names of Namespaces - -As with other naming guidelines, the goal when naming namespaces is creating sufficient clarity for the programmer using the framework to immediately know what the content of the namespace is likely to be. The following template specifies the general rule for naming namespaces: - - `.(|)[.][.]` - - The following are examples: - - `Fabrikam.Math` - `Litware.Security` - - ✔️ DO prefix namespace names with a company name to prevent namespaces from different companies from having the same name. - - ✔️ DO use a stable, version-independent product name at the second level of a namespace name. - - ❌ DO NOT use organizational hierarchies as the basis for names in namespace hierarchies, because group names within corporations tend to be short-lived. Organize the hierarchy of namespaces around groups of related technologies. - - ✔️ DO use PascalCasing, and separate namespace components with periods (e.g., `Microsoft.Office.PowerPoint`). If your brand employs nontraditional casing, you should follow the casing defined by your brand, even if it deviates from normal namespace casing. - - ✔️ CONSIDER using plural namespace names where appropriate. - - For example, use `System.Collections` instead of `System.Collection`. Brand names and acronyms are exceptions to this rule, however. For example, use `System.IO` instead of `System.IOs`. - - ❌ DO NOT use the same name for a namespace and a type in that namespace. - - For example, do not use `Debug` as a namespace name and then also provide a class named `Debug` in the same namespace. Several compilers require such types to be fully qualified. - -### Namespaces and Type Name Conflicts - - ❌ DO NOT introduce generic type names such as `Element`, `Node`, `Log`, and `Message`. - - There is a very high probability that doing so will lead to type name conflicts in common scenarios. You should qualify the generic type names (`FormElement`, `XmlNode`, `EventLog`, `SoapMessage`). - - There are specific guidelines for avoiding type name conflicts for different categories of namespaces. - -- **Application model namespaces** - - Namespaces belonging to a single application model are very often used together, but they are almost never used with namespaces of other application models. For example, the namespace is very rarely used together with the namespace. The following is a list of well-known application model namespace groups: - - `System.Windows*` - `System.Web.UI*` - - ❌ DO NOT give the same name to types in namespaces within a single application model. - - For example, do not add a type named `Page` to the namespace, because the namespace already contains a type named `Page`. - -- **Infrastructure namespaces** - - This group contains namespaces that are rarely imported during development of common applications. For example, `.Design` namespaces are mainly used when developing programming tools. Avoiding conflicts with types in these namespaces is not critical. - -- **Core namespaces** - - Core namespaces include all `System` namespaces, excluding namespaces of the application models and the Infrastructure namespaces. Core namespaces include, among others, `System`, `System.IO`, `System.Xml`, and `System.Net`. - - ❌ DO NOT give types names that would conflict with any type in the Core namespaces. - - For example, never use `Stream` as a type name. It would conflict with , a very commonly used type. - -- **Technology namespace groups** - - This category includes all namespaces with the same first two namespace nodes `(.*`), such as `Microsoft.Build.Utilities` and `Microsoft.Build.Tasks`. It is important that types belonging to a single technology do not conflict with each other. - - ❌ DO NOT assign type names that would conflict with other types within a single technology. - - ❌ DO NOT introduce type name conflicts between types in technology namespaces and an application model namespace (unless the technology is not intended to be used with the application model). - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Naming Guidelines](naming-guidelines.md) diff --git a/docs/standard/design-guidelines/names-of-type-members.md b/docs/standard/design-guidelines/names-of-type-members.md deleted file mode 100644 index c0fcbf334ae57..0000000000000 --- a/docs/standard/design-guidelines/names-of-type-members.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "Names of Type Members" -description: Learn the guidelines for naming type members in .NET, such as methods, properties, events, and fields. -ms.date: "10/22/2008" -helpviewer_keywords: - - "events [.NET Framework], names" - - "methods [.NET Framework], names" - - "type members" - - "properties [.NET Framework], names" - - "fields, names" - - "field names" - - "names [.NET Framework], type members" - - "members [.NET Framework], type" -ms.assetid: af5a0903-36af-4c2a-b848-cf959affeaa5 ---- -# Names of Type Members - -Types are made of members: methods, properties, events, constructors, and fields. The following sections describe guidelines for naming type members. - -## Names of Methods - - Because methods are the means of taking action, the design guidelines require that method names be verbs or verb phrases. Following this guideline also serves to distinguish method names from property and type names, which are noun or adjective phrases. - - ✔️ DO give methods names that are verbs or verb phrases. - -```csharp -public class String { - public int CompareTo(...); - public string[] Split(...); - public string Trim(); -} -``` - -## Names of Properties - - Unlike other members, properties should be given noun phrase or adjective names. That is because a property refers to data, and the name of the property reflects that. PascalCasing is always used for property names. - - ✔️ DO name properties using a noun, noun phrase, or adjective. - - ❌ DO NOT have properties that match the name of "Get" methods as in the following example: - - `public string TextWriter { get {...} set {...} }` - `public string GetTextWriter(int value) { ... }` - - This pattern typically indicates that the property should really be a method. - - ✔️ DO name collection properties with a plural phrase describing the items in the collection instead of using a singular phrase followed by "List" or "Collection". - - ✔️ DO name Boolean properties with an affirmative phrase (`CanSeek` instead of `CantSeek`). Optionally, you can also prefix Boolean properties with "Is", "Can", or "Has", but only where it adds value. - - ✔️ CONSIDER giving a property the same name as its type. - - For example, the following property correctly gets and sets an enum value named `Color`, so the property is named `Color`: - -```csharp -public enum Color {...} -public class Control { - public Color Color { get {...} set {...} } -} -``` - -## Names of Events - - Events always refer to some action, either one that is happening or one that has occurred. Therefore, as with methods, events are named with verbs, and verb tense is used to indicate the time when the event is raised. - - ✔️ DO name events with a verb or a verb phrase. - - Examples include `Clicked`, `Painting`, `DroppedDown`, and so on. - - ✔️ DO give events names with a concept of before and after, using the present and past tenses. - - For example, a close event that is raised before a window is closed would be called `Closing`, and one that is raised after the window is closed would be called `Closed`. - - ❌ DO NOT use "Before" or "After" prefixes or postfixes to indicate pre- and post-events. Use present and past tenses as just described. - - ✔️ DO name event handlers (delegates used as types of events) with the "EventHandler" suffix, as shown in the following example: - - `public delegate void ClickedEventHandler(object sender, ClickedEventArgs e);` - - ✔️ DO use two parameters named `sender` and `e` in event handlers. - - The sender parameter represents the object that raised the event. The sender parameter is typically of type `object`, even if it is possible to employ a more specific type. - - ✔️ DO name event argument classes with the "EventArgs" suffix. - -## Names of Fields - - The field-naming guidelines apply to static public and protected fields. Internal and private fields are not covered by guidelines, and public or protected instance fields are not allowed by the [member design guidelines](member.md). - - ✔️ DO use PascalCasing in field names. - - ✔️ DO name fields using a noun, noun phrase, or adjective. - - ❌ DO NOT use a prefix for field names. - - For example, do not use "g_" or "s_" to indicate static fields. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Naming Guidelines](naming-guidelines.md) diff --git a/docs/standard/design-guidelines/naming-guidelines.md b/docs/standard/design-guidelines/naming-guidelines.md deleted file mode 100644 index b39392025fcfb..0000000000000 --- a/docs/standard/design-guidelines/naming-guidelines.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Naming Guidelines" -description: In this overview, read about naming conventions to use in framework development. Go to articles covering capitalization, general naming, and other guidelines. -ms.date: "10/22/2008" -helpviewer_keywords: - - "names [.NET Framework], about naming guidelines" - - "naming guidelines [.NET Framework]" - - "class library design guidelines [.NET Framework], names" - - "formatting [.NET Framework], names" - - "identifiers, class library element names" - - "names [.NET Framework]" - - "format naming guidelines [.NET Framework]" -ms.assetid: fc076d66-9b5f-42d3-aa65-61d970c794a3 ---- -# Naming Guidelines - -Following a consistent set of naming conventions in the development of a framework can be a major contribution to the framework’s usability. It allows the framework to be used by many developers on widely separated projects. Beyond consistency of form, names of framework elements must be easily understood and must convey the function of each element. - - The goal of this chapter is to provide a consistent set of naming conventions that results in names that make immediate sense to developers. - - Although adopting these naming conventions as general code development guidelines would result in more consistent naming throughout your code, you are required only to apply them to APIs that are publicly exposed (public or protected types and members, and explicitly implemented interfaces). - -## In This Section - - [Capitalization Conventions](capitalization-conventions.md) - [General Naming Conventions](general-naming-conventions.md) - [Names of Assemblies and DLLs](names-of-assemblies-and-dlls.md) - [Names of Namespaces](names-of-namespaces.md) - [Names of Classes, Structs, and Interfaces](names-of-classes-structs-and-interfaces.md) - [Names of Type Members](names-of-type-members.md) - [Naming Parameters](naming-parameters.md) - [Naming Resources](naming-resources.md) - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/naming-parameters.md b/docs/standard/design-guidelines/naming-parameters.md deleted file mode 100644 index ab305f42743e9..0000000000000 --- a/docs/standard/design-guidelines/naming-parameters.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: "Naming Parameters" -description: Learn guidelines for the naming of parameters. For example, use descriptive parameter names & camel casing, & consider naming based on meaning instead of type. -ms.date: "10/22/2008" -helpviewer_keywords: - - "parameters, names" - - "names [.NET Framework], parameters" -ms.assetid: ca3c956e-725a-441b-b4e3-eab5d472f41c ---- -# Naming Parameters - -Beyond the obvious reason of readability, it is important to follow the guidelines for parameter names because parameters are displayed in documentation and in the designer when visual design tools provide Intellisense and class browsing functionality. - - ✔️ DO use camelCasing in parameter names. - - ✔️ DO use descriptive parameter names. - - ✔️ CONSIDER using names based on a parameter’s meaning rather than the parameter’s type. - -### Naming Operator Overload Parameters - - ✔️ DO use `left` and `right` for binary operator overload parameter names if there is no meaning to the parameters. - - ✔️ DO use `value` for unary operator overload parameter names if there is no meaning to the parameters. - - ✔️ CONSIDER meaningful names for operator overload parameters if doing so adds significant value. - - ❌ DO NOT use abbreviations or numeric indices for operator overload parameter names. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Naming Guidelines](naming-guidelines.md) diff --git a/docs/standard/design-guidelines/naming-resources.md b/docs/standard/design-guidelines/naming-resources.md deleted file mode 100644 index 848e83b1590df..0000000000000 --- a/docs/standard/design-guidelines/naming-resources.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Naming Resources" -description: Review naming guidelines for resources in .NET, which are similar to the guidelines for naming properties. -ms.date: "10/22/2008" -helpviewer_keywords: - - "names [.NET Framework], localized resources" - - "localization, naming guidelines" - - "resource names" - - "global applications, naming guidelines" - - "international applications, naming guidelines" -ms.assetid: 8b0e97f3-7877-44fd-bc76-e05d36d5d79c ---- -# Naming Resources - -Because localizable resources can be referenced via certain objects as if they were properties, the naming guidelines for resources are similar to property guidelines. - - ✔️ DO use PascalCasing in resource keys. - - ✔️ DO provide descriptive rather than short identifiers. - - ❌ DO NOT use language-specific keywords of the main CLR languages. - - ✔️ DO use only alphanumeric characters and underscores in naming resources. - - ✔️ DO use the following naming convention for exception message resources. - - The resource identifier should be the exception type name plus a short identifier of the exception: - - `ArgumentExceptionIllegalCharacters` - `ArgumentExceptionInvalidName` - `ArgumentExceptionFileNameIsMalformed` - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Naming Guidelines](naming-guidelines.md) diff --git a/docs/standard/design-guidelines/nested-types.md b/docs/standard/design-guidelines/nested-types.md deleted file mode 100644 index 53fbb9143c6c6..0000000000000 --- a/docs/standard/design-guidelines/nested-types.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -description: "Learn more about: Nested Types" -title: "Nested Types" -ms.date: "10/22/2008" -helpviewer_keywords: - - "types, nested" - - "public nested types" - - "type design guidelines, nested types" - - "nested types" - - "members [.NET Framework], type" - - "class library design guidelines [.NET Framework], nested types" -ms.assetid: 12feb7f0-b793-4d96-b090-42d6473bab8c ---- -# Nested Types - -A nested type is a type defined within the scope of another type, which is called the enclosing type. A nested type has access to all members of its enclosing type. For example, it has access to private fields defined in the enclosing type and to protected fields defined in all ascendants of the enclosing type. - - In general, nested types should be used sparingly. There are several reasons for this. Some developers are not fully familiar with the concept. These developers might, for example, have problems with the syntax of declaring variables of nested types. Nested types are also very tightly coupled with their enclosing types, and as such are not suited to be general-purpose types. - - Nested types are best suited for modeling implementation details of their enclosing types. The end user should rarely have to declare variables of a nested type and almost never should have to explicitly instantiate nested types. For example, the enumerator of a collection can be a nested type of that collection. Enumerators are usually instantiated by their enclosing type, and because many languages support the foreach statement, enumerator variables rarely have to be declared by the end user. - - ✔️ DO use nested types when the relationship between the nested type and its outer type is such that member-accessibility semantics are desirable. - - ❌ DO NOT use public nested types as a logical grouping construct; use namespaces for this. - - ❌ AVOID publicly exposed nested types. The only exception to this is if variables of the nested type need to be declared only in rare scenarios such as subclassing or other advanced customization scenarios. - - ❌ DO NOT use nested types if the type is likely to be referenced outside of the containing type. - - For example, an enum passed to a method defined on a class should not be defined as a nested type in the class. - - ❌ DO NOT use nested types if they need to be instantiated by client code. If a type has a public constructor, it should probably not be nested. - - If a type can be instantiated, that seems to indicate the type has a place in the framework on its own (you can create it, work with it, and destroy it without ever using the outer type), and thus should not be nested. Inner types should not be widely reused outside of the outer type without any relationship whatsoever to the outer type. - - ❌ DO NOT define a nested type as a member of an interface. Many languages do not support such a construct. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Type Design Guidelines](type.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/operator-overloads.md b/docs/standard/design-guidelines/operator-overloads.md deleted file mode 100644 index 4657e0525cbfc..0000000000000 --- a/docs/standard/design-guidelines/operator-overloads.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -description: "Learn more about: Operator Overloads" -title: "Operator Overloads" -ms.date: "10/22/2008" -helpviewer_keywords: - - "operators [.NET Framework], overloads" - - "names [.NET Framework], overloaded operators" - - "member design guidelines, operators" - - "overloaded operators" -ms.assetid: 37585bf2-4c27-4dee-849a-af70e3338cc1 ---- -# Operator Overloads - -Operator overloads allow framework types to appear as if they were built-in language primitives. - - Although allowed and useful in some situations, operator overloads should be used cautiously. There are many cases in which operator overloading has been abused, such as when framework designers started to use operators for operations that should be simple methods. The following guidelines should help you decide when and how to use operator overloading. - - ❌ AVOID defining operator overloads, except in types that should feel like primitive (built-in) types. - - ✔️ CONSIDER defining operator overloads in a type that should feel like a primitive type. - - For example, has `operator==` and `operator!=` defined. - - ✔️ DO define operator overloads in structs that represent numbers (such as ). - - ❌ DO NOT be cute when defining operator overloads. - - Operator overloading is useful in cases in which it is immediately obvious what the result of the operation will be. For example, it makes sense to be able to subtract one from another `DateTime` and get a . However, it is not appropriate to use the logical union operator to union two database queries, or to use the shift operator to write to a stream. - - ❌ DO NOT provide operator overloads unless at least one of the operands is of the type defining the overload. - - ✔️ DO overload operators in a symmetric fashion. - - For example, if you overload the `operator==`, you should also overload the `operator!=`. Similarly, if you overload the `operator<`, you should also overload the `operator>`, and so on. - - ✔️ CONSIDER providing methods with friendly names that correspond to each overloaded operator. - - Many languages do not support operator overloading. For this reason, it is recommended that types that overload operators include a secondary method with an appropriate domain-specific name that provides equivalent functionality. - - The following table contains a list of operators and the corresponding friendly method names. - -|C# Operator Symbol|Metadata Name|Friendly Name| -|-------------------------|-------------------|-------------------| -|`N/A`|`op_Implicit`|`To/From`| -|`N/A`|`op_Explicit`|`To/From`| -|`+ (binary)`|`op_Addition`|`Add`| -|`- (binary)`|`op_Subtraction`|`Subtract`| -|`* (binary)`|`op_Multiply`|`Multiply`| -|`/`|`op_Division`|`Divide`| -|`%`|`op_Modulus`|`Mod or Remainder`| -|`^`|`op_ExclusiveOr`|`Xor`| -|`& (binary)`|`op_BitwiseAnd`|`BitwiseAnd`| -|||`op_BitwiseOr`|`BitwiseOr`| -|`&&`|`op_LogicalAnd`|`And`| -||||`op_LogicalOr`|`Or`| -|`=`|`op_Assign`|`Assign`| -|`<<`|`op_LeftShift`|`LeftShift`| -|`>>`|`op_RightShift`|`RightShift`| -|`N/A`|`op_SignedRightShift`|`SignedRightShift`| -|`N/A`|`op_UnsignedRightShift`|`UnsignedRightShift`| -|`==`|`op_Equality`|`Equals`| -|`!=`|`op_Inequality`|`Equals`| -|`>`|`op_GreaterThan`|`CompareTo`| -|`<`|`op_LessThan`|`CompareTo`| -|`>=`|`op_GreaterThanOrEqual`|`CompareTo`| -|`<=`|`op_LessThanOrEqual`|`CompareTo`| -|`*=`|`op_MultiplicationAssignment`|`Multiply`| -|`-=`|`op_SubtractionAssignment`|`Subtract`| -|`^=`|`op_ExclusiveOrAssignment`|`Xor`| -|`<<=`|`op_LeftShiftAssignment`|`LeftShift`| -|`%=`|`op_ModulusAssignment`|`Mod`| -|`+=`|`op_AdditionAssignment`|`Add`| -|`&=`|`op_BitwiseAndAssignment`|`BitwiseAnd`| -||=|`op_BitwiseOrAssignment`|`BitwiseOr`| -|`,`|`op_Comma`|`Comma`| -|`/=`|`op_DivisionAssignment`|`Divide`| -|`--`|`op_Decrement`|`Decrement`| -|`++`|`op_Increment`|`Increment`| -|`- (unary)`|`op_UnaryNegation`|`Negate`| -|`+ (unary)`|`op_UnaryPlus`|`Plus`| -|`~`|`op_OnesComplement`|`OnesComplement`| - -### Overloading Operator == - - Overloading `operator ==` is quite complicated. The semantics of the operator need to be compatible with several other members, such as . - -### Conversion Operators - - Conversion operators are unary operators that allow conversion from one type to another. The operators must be defined as static members on either the operand or the return type. There are two types of conversion operators: implicit and explicit. - - ❌ DO NOT provide a conversion operator if such conversion is not clearly expected by the end users. - - ❌ DO NOT define conversion operators outside of a type’s domain. - - For example, , , and are all numeric types, whereas is not. Therefore, there should be no conversion operator to convert a `Double(long)` to a `DateTime`. A constructor is preferred in such a case. - - ❌ DO NOT provide an implicit conversion operator if the conversion is potentially lossy. - - For example, there should not be an implicit conversion from `Double` to `Int32` because `Double` has a wider range than `Int32`. An explicit conversion operator can be provided even if the conversion is potentially lossy. - - ❌ DO NOT throw exceptions from implicit casts. - - It is very difficult for end users to understand what is happening, because they might not be aware that a conversion is taking place. - - ✔️ DO throw if a call to a cast operator results in a lossy conversion and the contract of the operator does not allow lossy conversions. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Member Design Guidelines](member.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/parameter-design.md b/docs/standard/design-guidelines/parameter-design.md deleted file mode 100644 index fc0446dae754b..0000000000000 --- a/docs/standard/design-guidelines/parameter-design.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -description: "Learn more about: Parameter Design" -title: "Parameter Design" -ms.date: "10/22/2008" -helpviewer_keywords: - - "member design guidelines [.NET Framework], parameters" - - "members [.NET Framework], parameters" - - "names [.NET Framework], parameters" - - "parameters, design guidelines" - - "reserved parameters" -ms.assetid: 3f33bf46-4a7b-43b3-bb78-1ffebe0dcfa6 ---- -# Parameter Design - -This section provides broad guidelines on parameter design, including sections with guidelines for checking arguments. In addition, you should refer to the guidelines described in [Naming Parameters](naming-parameters.md). - - ✔️ DO use the least derived parameter type that provides the functionality required by the member. - - For example, suppose you want to design a method that enumerates a collection and prints each item to the console. Such a method should take as the parameter, not or , for example. - - ❌ DO NOT use reserved parameters. - - If more input to a member is needed in some future version, a new overload can be added. - - ❌ DO NOT have publicly exposed methods that take pointers, arrays of pointers, or multidimensional arrays as parameters. - - Pointers and multidimensional arrays are relatively difficult to use properly. In almost all cases, APIs can be redesigned to avoid taking these types as parameters. - - ✔️ DO place all `out` parameters following all of the by-value and `ref` parameters (excluding parameter arrays), even if it results in an inconsistency in parameter ordering between overloads (see [Member Overloading](member-overloading.md)). - - The `out` parameters can be seen as extra return values, and grouping them together makes the method signature easier to understand. - - ✔️ DO be consistent in naming parameters when overriding members or implementing interface members. - - This better communicates the relationship between the methods. - -### Choosing Between Enum and Boolean Parameters - - ✔️ DO use enums if a member would otherwise have two or more Boolean parameters. - - ❌ DO NOT use Booleans unless you are absolutely sure there will never be a need for more than two values. - - Enums give you some room for future addition of values, but you should be aware of all the implications of adding values to enums, which are described in [Enum Design](enum.md). - - ✔️ CONSIDER using Booleans for constructor parameters that are truly two-state values and are simply used to initialize Boolean properties. - -### Validating Arguments - - ✔️ DO validate arguments passed to public, protected, or explicitly implemented members. Throw , or one of its subclasses, if the validation fails. - - Note that the actual validation does not necessarily have to happen in the public or protected member itself. It could happen at a lower level in some private or internal routine. The main point is that the entire surface area that is exposed to the end users checks the arguments. - - ✔️ DO throw if a null argument is passed and the member does not support null arguments. - - ✔️ DO validate enum parameters. - - Do not assume enum arguments will be in the range defined by the enum. The CLR allows casting any integer value into an enum value even if the value is not defined in the enum. - - ❌ DO NOT use for enum range checks. - - ✔️ DO be aware that mutable arguments might have changed after they were validated. - - If the member is security sensitive, you are encouraged to make a copy and then validate and process the argument. - -### Parameter Passing - - From the perspective of a framework designer, there are three main groups of parameters: by-value parameters, `ref` parameters, and `out` parameters. - - When an argument is passed through a by-value parameter, the member receives a copy of the actual argument passed in. If the argument is a value type, a copy of the argument is put on the stack. If the argument is a reference type, a copy of the reference is put on the stack. Most popular CLR languages, such as C#, VB.NET, and C++, default to passing parameters by value. - - When an argument is passed through a `ref` parameter, the member receives a reference to the actual argument passed in. If the argument is a value type, a reference to the argument is put on the stack. If the argument is a reference type, a reference to the reference is put on the stack. `Ref` parameters can be used to allow the member to modify arguments passed by the caller. - - `Out` parameters are similar to `ref` parameters, with some small differences. The parameter is initially considered unassigned and cannot be read in the member body before it is assigned some value. Also, the parameter has to be assigned some value before the member returns. - - ❌ AVOID using `out` or `ref` parameters. - - Using `out` or `ref` parameters requires experience with pointers, understanding how value types and reference types differ, and handling methods with multiple return values. Also, the difference between `out` and `ref` parameters is not widely understood. Framework architects designing for a general audience should not expect users to become proficient in working with `out` or `ref` parameters. - - ❌ DO NOT pass reference types by reference. - - There are some limited exceptions to the rule, such as a method that can be used to swap references. - -### Members with Variable Number of Parameters - - Members that can take a variable number of arguments are expressed by providing an array parameter. For example, provides the following method: - -```csharp -public class String { - public static string Format(string format, object[] parameters); -} -``` - - A user can then call the method, as follows: - - `String.Format("File {0} not found in {1}",new object[]{filename,directory});` - - Adding the C# params keyword to an array parameter changes the parameter to a so-called params array parameter and provides a shortcut to creating a temporary array. - -```csharp -public class String { - public static string Format(string format, params object[] parameters); -} -``` - - Doing this allows the user to call the method by passing the array elements directly in the argument list. - - `String.Format("File {0} not found in {1}",filename,directory);` - - Note that the params keyword can be added only to the last parameter in the parameter list. - - ✔️ CONSIDER adding the params keyword to array parameters if you expect the end users to pass arrays with a small number of elements. If it's expected that lots of elements will be passed in common scenarios, users will probably not pass these elements inline anyway, and so the params keyword is not necessary. - - ❌ AVOID using params arrays if the caller would almost always have the input already in an array. - - For example, members with byte array parameters would almost never be called by passing individual bytes. For this reason, byte array parameters in the .NET Framework do not use the params keyword. - - ❌ DO NOT use params arrays if the array is modified by the member taking the params array parameter. - - Because of the fact that many compilers turn the arguments to the member into a temporary array at the call site, the array might be a temporary object, and therefore any modifications to the array will be lost. - - ✔️ CONSIDER using the params keyword in a simple overload, even if a more complex overload could not use it. - - Ask yourself if users would value having the params array in one overload even if it wasn't in all overloads. - - ✔️ DO try to order parameters to make it possible to use the params keyword. - - ✔️ CONSIDER providing special overloads and code paths for calls with a small number of arguments in extremely performance-sensitive APIs. - - This makes it possible to avoid creating array objects when the API is called with a small number of arguments. Form the names of the parameters by taking a singular form of the array parameter and adding a numeric suffix. - - You should only do this if you are going to special-case the entire code path, not just create an array and call the more general method. - - ✔️ DO be aware that null could be passed as a params array argument. - - You should validate that the array is not null before processing. - - ❌ DO NOT use the `varargs` methods, otherwise known as the ellipsis. - - Some CLR languages, such as C++, support an alternative convention for passing variable parameter lists called `varargs` methods. The convention should not be used in frameworks, because it is not CLS compliant. - -### Pointer Parameters - - In general, pointers should not appear in the public surface area of a well-designed managed code framework. Most of the time, pointers should be encapsulated. However, in some cases pointers are required for interoperability reasons, and using pointers in such cases is appropriate. - - ✔️ DO provide an alternative for any member that takes a pointer argument, because pointers are not CLS-compliant. - - ❌ AVOID doing expensive argument checking of pointer arguments. - - ✔️ DO follow common pointer-related conventions when designing members with pointers. - - For example, there is no need to pass the start index, because simple pointer arithmetic can be used to accomplish the same result. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Member Design Guidelines](member.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/property.md b/docs/standard/design-guidelines/property.md deleted file mode 100644 index b90722342c4b6..0000000000000 --- a/docs/standard/design-guidelines/property.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -description: "Learn more about: Property Design" -title: "Property Design" -ms.date: "10/22/2008" -helpviewer_keywords: - - "member design guidelines, properties" - - "properties [.NET Framework], design guidelines" -ms.assetid: 127cbc0c-cbed-48fd-9c89-7c5d4f98f163 ---- -# Property Design - -Although properties are technically very similar to methods, they are quite different in terms of their usage scenarios. They should be seen as smart fields. They have the calling syntax of fields, and the flexibility of methods. - - ✔️ DO create get-only properties if the caller should not be able to change the value of the property. - - Keep in mind that if the type of the property is a mutable reference type, the property value can be changed even if the property is get-only. - - ❌ DO NOT provide set-only properties or properties with the setter having broader accessibility than the getter. - - For example, do not use properties with a public setter and a protected getter. - - If the property getter cannot be provided, implement the functionality as a method instead. Consider starting the method name with `Set` and follow with what you would have named the property. For example, has a method called `SetCachePath` instead of having a set-only property called `CachePath`. - - ✔️ DO provide sensible default values for all properties, ensuring that the defaults do not result in a security hole or terribly inefficient code. - - ✔️ DO allow properties to be set in any order even if this results in a temporary invalid state of the object. - - It is common for two or more properties to be interrelated to a point where some values of one property might be invalid given the values of other properties on the same object. In such cases, exceptions resulting from the invalid state should be postponed until the interrelated properties are actually used together by the object. - - ✔️ DO preserve the previous value if a property setter throws an exception. - - ❌ AVOID throwing exceptions from property getters. - - Property getters should be simple operations and should not have any preconditions. If a getter can throw an exception, it should probably be redesigned to be a method. Notice that this rule does not apply to indexers, where we do expect exceptions as a result of validating the arguments. - -### Indexed Property Design - - An indexed property is a special property that can have parameters and can be called with special syntax similar to array indexing. - - Indexed properties are commonly referred to as indexers. Indexers should be used only in APIs that provide access to items in a logical collection. For example, a string is a collection of characters, and the indexer on was added to access its characters. - - ✔️ CONSIDER using indexers to provide access to data stored in an internal array. - - ✔️ CONSIDER providing indexers on types representing collections of items. - - ❌ AVOID using indexed properties with more than one parameter. - - If the design requires multiple parameters, reconsider whether the property really represents an accessor to a logical collection. If it does not, use methods instead. Consider starting the method name with `Get` or `Set`. - - ❌ AVOID indexers with parameter types other than , , , , or an enum. - - If the design requires other types of parameters, strongly reevaluate whether the API really represents an accessor to a logical collection. If it does not, use a method. Consider starting the method name with `Get` or `Set`. - - ✔️ DO use the name `Item` for indexed properties unless there is an obviously better name (e.g., see the property on `System.String`). - - In C#, indexers are by default named Item. The can be used to customize this name. - - ❌ DO NOT provide both an indexer and methods that are semantically equivalent. - - ❌ DO NOT provide more than one family of overloaded indexers in one type. - - This is enforced by the C# compiler. - - ❌ DO NOT use nondefault indexed properties. - - This is enforced by the C# compiler. - -### Property Change Notification Events - - Sometimes it is useful to provide an event notifying the user of changes in a property value. For example, `System.Windows.Forms.Control` raises a `TextChanged` event after the value of its `Text` property has changed. - - ✔️ CONSIDER raising change notification events when property values in high-level APIs (usually designer components) are modified. - - If there is a good scenario for a user to know when a property of an object is changing, the object should raise a change notification event for the property. - - However, it is unlikely to be worth the overhead to raise such events for low-level APIs such as base types or collections. For example, would not raise such events when a new item is added to the list and the `Count` property changes. - - ✔️ CONSIDER raising change notification events when the value of a property changes via external forces. - - If a property value changes via some external force (in a way other than by calling methods on the object), raise events indicate to the developer that the value is changing and has changed. A good example is the `Text` property of a text box control. When the user types text in a `TextBox`, the property value automatically changes. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Member Design Guidelines](member.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/protected-members.md b/docs/standard/design-guidelines/protected-members.md deleted file mode 100644 index 05df6281cb5e3..0000000000000 --- a/docs/standard/design-guidelines/protected-members.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: "Learn more about: Protected Members" -title: "Protected Members" -ms.date: "10/22/2008" -helpviewer_keywords: - - "members [.NET Framework], protected" - - "protected members" - - "classes [.NET Framework], unsealed" - - "classes [.NET Framework], protected members" - - "unsealed classes" - - "customizing class behavior" -ms.assetid: aa0b58ee-3956-494d-ab48-471ae5db8740 ---- -# Protected Members - -Protected members by themselves do not provide any extensibility, but they can make extensibility through subclassing more powerful. They can be used to expose advanced customization options without unnecessarily complicating the main public interface. - - Framework designers need to be careful with protected members because the name "protected" can give a false sense of security. Anyone is able to subclass an unsealed class and access protected members, and so all the same defensive coding practices used for public members apply to protected members. - - ✔️ CONSIDER using protected members for advanced customization. - - ✔️ DO treat protected members in unsealed classes as public for the purpose of security, documentation, and compatibility analysis. - - Anyone can inherit from a class and access the protected members. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Designing for Extensibility](designing-for-extensibility.md) diff --git a/docs/standard/design-guidelines/sealing.md b/docs/standard/design-guidelines/sealing.md deleted file mode 100644 index 018f91182d335..0000000000000 --- a/docs/standard/design-guidelines/sealing.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -description: "Learn more about: Sealing" -title: "Sealing" -ms.date: "10/22/2008" -helpviewer_keywords: - - "limiting extensibility" - - "classes [.NET Framework], sealing" - - "preventing customization" - - "sealed classes" -ms.assetid: cc42267f-bb7a-427a-845e-df97408528d4 ---- -# Sealing - -One of the features of object-oriented frameworks is that developers can extend and customize them in ways unanticipated by the framework designers. This is both the power and danger of extensible design. When you design your framework, it is, therefore, very important to carefully design for extensibility when it is desired, and to limit extensibility when it is dangerous. - - A powerful mechanism that prevents extensibility is sealing. You can seal either the class or individual members. Sealing a class prevents users from inheriting from the class. Sealing a member prevents users from overriding a particular member. - - ❌ DO NOT seal classes without having a good reason to do so. - - Sealing a class because you cannot think of an extensibility scenario is not a good reason. Framework users like to inherit from classes for various nonobvious reasons, like adding convenience members. See [Unsealed Classes](unsealed-classes.md) for examples of nonobvious reasons users want to inherit from a type. - - Good reasons for sealing a class include the following: - -- The class is a static class. See [Static Class Design](static-class.md). - -- The class stores security-sensitive secrets in inherited protected members. - -- The class inherits many virtual members and the cost of sealing them individually would outweigh the benefits of leaving the class unsealed. - -- The class is an attribute that requires very fast runtime look-up. Sealed attributes have slightly higher performance levels than unsealed ones. See [Attributes](attributes.md). - - ❌ DO NOT declare protected or virtual members on sealed types. - - By definition, sealed types cannot be inherited from. This means that protected members on sealed types cannot be called, and virtual methods on sealed types cannot be overridden. - - ✔️ CONSIDER sealing members that you override. - - Problems that can result from introducing virtual members (discussed in [Virtual Members](virtual-members.md)) apply to overrides as well, although to a slightly lesser degree. Sealing an override shields you from these problems starting from that point in the inheritance hierarchy. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Designing for Extensibility](designing-for-extensibility.md) -- [Unsealed Classes](unsealed-classes.md) diff --git a/docs/standard/design-guidelines/serialization.md b/docs/standard/design-guidelines/serialization.md deleted file mode 100644 index 9370f00a1cff3..0000000000000 --- a/docs/standard/design-guidelines/serialization.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -description: "Learn more about: Serialization" -title: "Serialization" -ms.date: "10/22/2008" -ms.assetid: bebb27ac-9712-4196-9931-de19fc04dbac ---- -# Serialization - -Serialization is the process of converting an object into a format that can be readily persisted or transported. For example, you can serialize an object, transport it over the Internet using HTTP, and deserialized it at the destination machine. - - The .NET Framework offers three main serialization technologies optimized for various serialization scenarios. The following table lists these technologies and the main Framework types related to these technologies. - -|**Technology Name**|**Main Types**|**Scenarios**| -|-------------------------|--------------------|-------------------| -|**Data Contract Serialization**|




|General persistence
Web Services
JSON| -|**XML Serialization**||XML format with full control over the shape of the XML| -|**Runtime Serialization (Binary and SOAP)**|


|.NET Remoting| - - ✔️ DO think about serialization when you design new types. - -## Choosing the Right Serialization Technology to Support - - ✔️ CONSIDER supporting Data Contract Serialization if instances of your type might need to be persisted or used in Web Services. - - ✔️ CONSIDER supporting the XML Serialization instead of or in addition to Data Contract Serialization if you need more control over the XML format that is produced when the type is serialized. - - This may be necessary in some interoperability scenarios where you need to use an XML construct that is not supported by Data Contract Serialization, for example, to produce XML attributes. - - ✔️ CONSIDER supporting the Runtime Serialization if instances of your type need to travel across .NET Remoting boundaries. - - ❌ AVOID supporting Runtime Serialization or XML Serialization just for general persistence reasons. Prefer Data Contract Serialization instead. - -## Supporting Data Contract Serialization - - Types can support Data Contract Serialization by applying the to the type and the to the members (fields and properties) of the type. - - ✔️ CONSIDER marking data members of your type public if the type can be used in partial trust. - - In full trust, Data Contract serializers can serialize and deserialize nonpublic types and members, but only public members can be serialized and deserialized in partial trust. - - ✔️ DO implement a getter and setter on all properties that have . Data Contract serializers require both the getter and the setter for the type to be considered serializable. (In .NET Framework 3.5 SP1, some collection properties can be get-only.) If the type won’t be used in partial trust, one or both of the property accessors can be nonpublic. - - ✔️ CONSIDER using the serialization callbacks for initialization of deserialized instances. - - Constructors are not called when objects are deserialized. (There are exceptions to the rule. Constructors of collections marked with are called during deserialization.) Therefore, any logic that executes during normal construction needs to be implemented as one of the serialization callbacks. - - `OnDeserializedAttribute` is the most commonly used callback attribute. The other attributes in the family are , , and . They can be used to mark callbacks that get executed before deserialization, before serialization, and finally, after serialization, respectively. - - ✔️ CONSIDER using the to indicate concrete types that should be used when deserializing a complex object graph. - - ✔️ DO consider backward and forward compatibility when creating or changing serializable types. - - Keep in mind that serialized streams of future versions of your type can be deserialized into the current version of the type, and vice versa. - - Make sure you understand that data members, even private and internal, cannot change their names, types, or even their order in future versions of the type unless special care is taken to preserve the contract using explicit parameters to the data contract attributes. - - Test compatibility of serialization when making changes to serializable types. Try deserializing the new version into an old version, and vice versa. - - ✔️ CONSIDER implementing to allow round-tripping between different versions of the type. - - The interface allows the serializer to ensure that no data is lost during round-tripping. The property is used to store any data from the future version of the type that is unknown to the current version, and so it cannot store it in its data members. When the current version is subsequently serialized and deserialized into a future version, the additional data will be available in the serialized stream. - -## Supporting XML Serialization - - Data Contract Serialization is the main (default) serialization technology in the .NET Framework, but there are serialization scenarios that Data Contract Serialization does not support. For example, it does not give you full control over the shape of XML produced or consumed by the serializer. If such fine control is required, XML Serialization has to be used, and you need to design your types to support this serialization technology. - - ❌ AVOID designing your types specifically for XML Serialization, unless you have a very strong reason to control the shape of the XML produced. This serialization technology has been superseded by the Data Contract Serialization discussed in the previous section. - - ✔️ CONSIDER implementing the interface if you want even more control over the shape of the serialized XML than what’s offered by applying the XML Serialization attributes. Two methods of the interface, and , allow you to fully control the serialized XML stream. You can also control the XML schema that gets generated for the type by applying the `XmlSchemaProviderAttribute`. - -## Supporting Runtime Serialization - - Runtime Serialization is a technology used by .NET Remoting. If you think your types will be transported using .NET Remoting, you need to make sure they support Runtime Serialization. - - The basic support for Runtime Serialization can be provided by applying the , and more advanced scenarios involve implementing a simple Runtime Serializable Pattern (implement and provide serialization constructor). - - ✔️ CONSIDER supporting Runtime Serialization if your types will be used with .NET Remoting. For example, the namespace uses .NET Remoting, and so all types exchanged between `System.AddIn` add-ins need to support Runtime Serialization. - - ✔️ CONSIDER implementing the Runtime Serializable Pattern if you want complete control over the serialization process. For example, if you want to transform data as it gets serialized or deserialized. - - The pattern is very simple. All you need to do is implement the interface and provide a special constructor that is used when the object is deserialized. - - ✔️ DO make the serialization constructor protected and provide two parameters typed and named exactly as shown in the sample here. - -```csharp -[Serializable] -public class Person : ISerializable -{ - protected Person(SerializationInfo info, StreamingContext context) - { - // ... - } -} -``` - - ✔️ DO implement the members explicitly. - - ✔️ DO apply a link demand to implementation. This ensures that only fully trusted core and the Runtime Serializer have access to the member. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Usage Guidelines](usage-guidelines.md) diff --git a/docs/standard/design-guidelines/static-class.md b/docs/standard/design-guidelines/static-class.md deleted file mode 100644 index 52717bc3bdbbb..0000000000000 --- a/docs/standard/design-guidelines/static-class.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -description: "Learn more about: Static Class Design" -title: "Static Class Design" -ms.date: "10/22/2008" -helpviewer_keywords: - - "type design guidelines, static classes" - - "class library design guidelines [.NET Framework], classes" - - "classes [.NET Framework], static" - - "static classes [.NET Framework]" - - "classes [.NET Framework], design guidelines" - - "type design guidelines, classes" -ms.assetid: d67c14d8-c4dd-443f-affb-4ccae677c9b6 ---- -# Static Class Design - -A static class is defined as a class that contains only static members (of course besides the instance members inherited from and possibly a private constructor). Some languages provide built-in support for static classes. In C# 2.0 and later, when a class is declared to be static, it is sealed, abstract, and no instance members can be overridden or declared. - - Static classes are a compromise between pure object-oriented design and simplicity. They are commonly used to provide shortcuts to other operations (such as ), holders of extension methods, or functionality for which a full object-oriented wrapper is unwarranted (such as ). - - ✔️ DO use static classes sparingly. - - Static classes should be used only as supporting classes for the object-oriented core of the framework. - - ❌ DO NOT treat static classes as a miscellaneous bucket. - - ❌ DO NOT declare or override instance members in static classes. - - ✔️ DO declare static classes as sealed, abstract, and add a private instance constructor if your programming language does not have built-in support for static classes. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Type Design Guidelines](type.md) -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/struct.md b/docs/standard/design-guidelines/struct.md deleted file mode 100644 index 8c2c1c7671ee7..0000000000000 --- a/docs/standard/design-guidelines/struct.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -description: "Learn more about: Struct Design" -title: "Struct Design" -ms.date: "10/22/2008" -helpviewer_keywords: - - "class library design guidelines [.NET Framework], structures" - - "deallocating structures" - - "allocating structures" - - "value types, structures" - - "structure design" - - "type design guidelines, structures" - - "structures [.NET Framework], design guidelines" -ms.assetid: 1f48b2d8-608c-4be6-9ba4-d8f203ed9f9f ---- -# Struct Design - -The general-purpose value type is most often referred to as a struct, its C# keyword. This section provides guidelines for general struct design. - - ❌ DO NOT provide a parameterless constructor for a struct. - - Following this guideline allows arrays of structs to be created without having to run the constructor on each item of the array. Notice that C# does not allow structs to have parameterless constructors. - - ❌ DO NOT define mutable value types. - - Mutable value types have several problems. For example, when a property getter returns a value type, the caller receives a copy. Because the copy is created implicitly, developers might not be aware that they are mutating the copy, and not the original value. Also, some languages (dynamic languages, in particular) have problems using mutable value types because even local variables, when dereferenced, cause a copy to be made. - - ✔️ DO ensure that a state where all instance data is set to zero, false, or null (as appropriate) is valid. - - This prevents accidental creation of invalid instances when an array of the structs is created. - - ✔️ DO implement on value types. - - The method on value types causes boxing, and its default implementation is not very efficient, because it uses reflection. can have much better performance and can be implemented so that it will not cause boxing. - - ❌ DO NOT explicitly extend . In fact, most languages prevent this. - - In general, structs can be very useful but should only be used for small, single, immutable values that will not be boxed frequently. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Type Design Guidelines](type.md) -- [Framework Design Guidelines](index.md) -- [Choosing Between Class and Struct](choosing-between-class-and-struct.md) diff --git a/docs/standard/design-guidelines/system-xml-usage.md b/docs/standard/design-guidelines/system-xml-usage.md deleted file mode 100644 index da645986a1e6b..0000000000000 --- a/docs/standard/design-guidelines/system-xml-usage.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: "Learn more about: System.Xml Usage" -title: "System.Xml Usage" -ms.date: "10/22/2008" -ms.assetid: 82302f0d-a621-4c6f-b57d-999bd61f21a6 ---- -# System.Xml Usage - -This section talks about usage of several types residing in namespaces that can be used to represent XML data. - - ❌ DO NOT use or to represent XML data. Favor using instances of , , , or subtypes of instead. `XmlNode` and `XmlDocument` are not designed for exposing in public APIs. - - ✔️ DO use `XmlReader`, `IXPathNavigable`, or subtypes of `XNode` as input or output of members that accept or return XML. - - Use these abstractions instead of `XmlDocument`, `XmlNode`, or , because this decouples the methods from specific implementations of an in-memory XML document and allows them to work with virtual XML data sources that expose `XNode`, `XmlReader`, or . - - ❌ DO NOT subclass `XmlDocument` if you want to create a type representing an XML view of an underlying object model or data source. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Usage Guidelines](usage-guidelines.md) diff --git a/docs/standard/design-guidelines/type.md b/docs/standard/design-guidelines/type.md deleted file mode 100644 index 7643fb9226339..0000000000000 --- a/docs/standard/design-guidelines/type.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -description: "Learn more about: Type Design Guidelines" -title: "Type Design Guidelines" -ms.date: "10/22/2008" -helpviewer_keywords: - - "type design guidelines" - - "type design guidelines, about type design guidelines" - - "class library design guidelines [.NET Framework], type design guidelines" - - "types [.NET Framework], design guidelines" -ms.assetid: 6b49314e-8bba-43ea-97ca-4e0255812f95 ---- -# Type Design Guidelines - -From the CLR perspective, there are only two categories of types—reference types and value types—but for the purpose of a discussion about framework design, we divide types into more logical groups, each with its own specific design rules. - - Classes are the general case of reference types. They make up the bulk of types in the majority of frameworks. Classes owe their popularity to the rich set of object-oriented features they support and to their general applicability. Base classes and abstract classes are special logical groups related to extensibility. - - Interfaces are types that can be implemented by both reference types and value types. They can thus serve as roots of polymorphic hierarchies of reference types and value types. In addition, interfaces can be used to simulate multiple inheritance, which is not natively supported by the CLR. - - Structs are the general case of value types and should be reserved for small, simple types, similar to language primitives. - - Enums are a special case of value types used to define short sets of values, such as days of the week, console colors, and so on. - - Static classes are types intended to be containers for static members. They are commonly used to provide shortcuts to other operations. - - Delegates, exceptions, attributes, arrays, and collections are all special cases of reference types intended for specific uses, and guidelines for their design and usage are discussed elsewhere in this book. - - ✔️ DO ensure that each type is a well-defined set of related members, not just a random collection of unrelated functionality. - -## In This Section - - [Choosing Between Class and Struct](choosing-between-class-and-struct.md) - [Abstract Class Design](abstract-class.md) - [Static Class Design](static-class.md) - [Interface Design](interface.md) - [Struct Design](struct.md) - [Enum Design](enum.md) - [Nested Types](nested-types.md) - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/unsealed-classes.md b/docs/standard/design-guidelines/unsealed-classes.md deleted file mode 100644 index 9ec54920dec63..0000000000000 --- a/docs/standard/design-guidelines/unsealed-classes.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: "Learn more about: Unsealed Classes" -title: "Unsealed Classes" -ms.date: "10/22/2008" -helpviewer_keywords: - - "classes [.NET Framework], unsealed" - - "unsealed classes" - - "inheritance, classes" -ms.assetid: 9a3bd505-90f5-4053-9f0d-3cf5fa3d3ebf ---- -# Unsealed Classes - -Sealed classes cannot be inherited from, and they prevent extensibility. In contrast, classes that can be inherited from are called unsealed classes. - - ✔️ CONSIDER using unsealed classes with no added virtual or protected members as a great way to provide inexpensive yet much appreciated extensibility to a framework. - - Developers often want to inherit from unsealed classes so as to add convenience members such as custom constructors, new methods, or method overloads. For example, `System.Messaging.MessageQueue` is unsealed and thus allows users to create custom queues that default to a particular queue path or to add custom methods that simplify the API for specific scenarios. - - Classes are unsealed by default in most programming languages, and this is also the recommended default for most classes in frameworks. The extensibility afforded by unsealed types is much appreciated by framework users and quite inexpensive to provide because of relatively low test costs associated with unsealed types. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Designing for Extensibility](designing-for-extensibility.md) -- [Sealing](sealing.md) diff --git a/docs/standard/design-guidelines/usage-guidelines.md b/docs/standard/design-guidelines/usage-guidelines.md deleted file mode 100644 index 22f48fc68ea33..0000000000000 --- a/docs/standard/design-guidelines/usage-guidelines.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: "Learn more about: Usage guidelines" -title: "Usage guidelines" -ms.date: "10/22/2008" -helpviewer_keywords: - - "class library design guidelines [.NET Framework], usage guidelines" -ms.assetid: 42215ffa-a099-4a26-b14e-fb2bdb6f95b7 ---- -# Usage guidelines - -This section contains guidelines for using common types in publicly accessible APIs. It deals with direct usage of built-in Framework types (e.g., serialization attributes) and overloading common operators. - -The interface is not covered in this section, but is discussed in the [Dispose Pattern](../garbage-collection/implementing-dispose.md) section. - -> [!NOTE] -> For guidelines and additional information about other common, built-in .NET Framework types, see the reference topics for the following: , , , , , , , . - -## In this section - -[Arrays](arrays.md) -[Attributes](attributes.md) -[Collections](guidelines-for-collections.md) -[Serialization](serialization.md) -[System.Xml Usage](system-xml-usage.md) -[Equality Operators](equality-operators.md) - -*Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - -*Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) diff --git a/docs/standard/design-guidelines/using-standard-exception-types.md b/docs/standard/design-guidelines/using-standard-exception-types.md deleted file mode 100644 index c09d4b49f8b72..0000000000000 --- a/docs/standard/design-guidelines/using-standard-exception-types.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "Using Standard Exception Types" -description: Read about standard exception types in .NET. Learn about SystemException, ApplicationException, ArgumentException, ComException, and more. -ms.date: "10/22/2008" -helpviewer_keywords: - - "throwing exceptions, standard types" - - "catching exceptions" - - "exceptions, catching" - - "exceptions, throwing" -ms.assetid: ab22ce03-78f9-4dca-8824-c7ed3bdccc27 ---- -# Using Standard Exception Types - -This section describes the standard exceptions provided by the Framework and the details of their usage. The list is by no means exhaustive. Please refer to the .NET Framework reference documentation for usage of other Framework exception types. - -## Exception and SystemException - - ❌ DO NOT throw or . - - ❌ DO NOT catch `System.Exception` or `System.SystemException` in framework code, unless you intend to rethrow. - - ❌ AVOID catching `System.Exception` or `System.SystemException`, except in top-level exception handlers. - -## ApplicationException - - ❌ DO NOT throw or derive from . - -## InvalidOperationException - - ✔️ DO throw an if the object is in an inappropriate state. - -## ArgumentException, ArgumentNullException, and ArgumentOutOfRangeException - - ✔️ DO throw or one of its subtypes if bad arguments are passed to a member. Prefer the most derived exception type, if applicable. - - ✔️ DO set the `ParamName` property when throwing one of the subclasses of `ArgumentException`. - - This property represents the name of the parameter that caused the exception to be thrown. Note that the property can be set using one of the constructor overloads. - - ✔️ DO use `value` for the name of the implicit value parameter of property setters. - -## NullReferenceException, IndexOutOfRangeException, and AccessViolationException - - ❌ DO NOT allow publicly callable APIs to explicitly or implicitly throw , , or . These exceptions are reserved and thrown by the execution engine and in most cases indicate a bug. - - Do argument checking to avoid throwing these exceptions. Throwing these exceptions exposes implementation details of your method that might change over time. - -## StackOverflowException - - ❌ DO NOT explicitly throw . The exception should be explicitly thrown only by the CLR. - - ❌ DO NOT catch `StackOverflowException`. - - It is almost impossible to write managed code that remains consistent in the presence of arbitrary stack overflows. The unmanaged parts of the CLR remain consistent by using probes to move stack overflows to well-defined places rather than by backing out from arbitrary stack overflows. - -## OutOfMemoryException - - ❌ DO NOT explicitly throw . This exception is to be thrown only by the CLR infrastructure. - -## ComException, SEHException, and ExecutionEngineException - - ❌ DO NOT explicitly throw , , and . These exceptions are to be thrown only by the CLR infrastructure. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Design Guidelines for Exceptions](exceptions.md) diff --git a/docs/standard/design-guidelines/virtual-members.md b/docs/standard/design-guidelines/virtual-members.md deleted file mode 100644 index 07b8fc417fd0e..0000000000000 --- a/docs/standard/design-guidelines/virtual-members.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -description: "Learn more about: Virtual Members" -title: "Virtual Members" -ms.date: "10/22/2008" -helpviewer_keywords: - - "overridable members" - - "virtual members" - - "members [.NET Framework], virtual" -ms.assetid: 8ff4eb97-0364-43ec-8a02-934b5cd94d19 ---- -# Virtual Members - -Virtual members can be overridden, thus changing the behavior of the subclass. They are quite similar to callbacks in terms of the extensibility they provide, but they are better in terms of execution performance and memory consumption. Also, virtual members feel more natural in scenarios that require creating a special kind of an existing type (specialization). - - Virtual members perform better than callbacks and events, but do not perform better than non-virtual methods. - - The main disadvantage of virtual members is that the behavior of a virtual member can only be modified at the time of compilation. The behavior of a callback can be modified at run time. - - Virtual members, like callbacks (and maybe more than callbacks), are costly to design, test, and maintain because any call to a virtual member can be overridden in unpredictable ways and can execute arbitrary code. Also, much more effort is usually required to clearly define the contract of virtual members, so the cost of designing and documenting them is higher. - - ❌ DO NOT make members virtual unless you have a good reason to do so and you are aware of all the costs related to designing, testing, and maintaining virtual members. - - Virtual members are less forgiving in terms of changes that can be made to them without breaking compatibility. Also, they are slower than non-virtual members, mostly because calls to virtual members are not inlined. - - ✔️ CONSIDER limiting extensibility to only what is absolutely necessary. - - ✔️ DO prefer protected accessibility over public accessibility for virtual members. Public members should provide extensibility (if required) by calling into a protected virtual member. - - The public members of a class should provide the right set of functionality for direct consumers of that class. Virtual members are designed to be overridden in subclasses, and protected accessibility is a great way to scope all virtual extensibility points to where they can be used. - - *Portions © 2005, 2009 Microsoft Corporation. All rights reserved.* - - *Reprinted by permission of Pearson Education, Inc. from [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition](https://www.informit.com/store/framework-design-guidelines-conventions-idioms-and-9780321545619) by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.* - -## See also - -- [Framework Design Guidelines](index.md) -- [Designing for Extensibility](designing-for-extensibility.md) diff --git a/docs/standard/threading/exceptions-in-managed-threads.md b/docs/standard/threading/exceptions-in-managed-threads.md index 361ba7a28f934..b1a8b15047a32 100644 --- a/docs/standard/threading/exceptions-in-managed-threads.md +++ b/docs/standard/threading/exceptions-in-managed-threads.md @@ -58,7 +58,7 @@ If you are migrating from .NET Framework 1.0 or 1.1 and took advantage of the ru - If a thread must be stopped so that process termination can proceed, make the thread a background thread so that it is automatically terminated on process exit. -In all cases, the strategy should follow the design guidelines for exceptions. See [Design Guidelines for Exceptions](../design-guidelines/exceptions.md). +In all cases, the strategy should follow the design guidelines for exceptions. See [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines). As a temporary compatibility measure, administrators can place a compatibility flag in the `` section of the application configuration file. This causes the common language runtime to revert to the behavior of versions 1.0 and 1.1. diff --git a/docs/visual-basic/developing-apps/customizing-extending-my/extending-the-my-namespace.md b/docs/visual-basic/developing-apps/customizing-extending-my/extending-the-my-namespace.md index 7655deb65d870..5f7652400f9ad 100644 --- a/docs/visual-basic/developing-apps/customizing-extending-my/extending-the-my-namespace.md +++ b/docs/visual-basic/developing-apps/customizing-extending-my/extending-the-my-namespace.md @@ -73,7 +73,7 @@ As is the case with most object models, some design patterns work well in the `M - **Simple parameter types.** Keep things simple by avoiding complex parameter types. Instead, create methods that either take no parameter input or that take simple input types such as strings, primitive types, and so on. - **Factory methods.** Some types are necessarily difficult to instantiate. Providing factory methods as extensions to the `My` namespace enables you to more easily discover and consume types that fall into this category. An example of a factory method that works well is `My.Computer.FileSystem.OpenTextFileReader`. There are several stream types available in the .NET Framework. By specifying text files specifically, the `OpenTextFileReader` helps the user understand which stream to use. -These guidelines do not preclude general design principles for class libraries. Rather, they are recommendations that are optimized for developers who are using Visual Basic and the `My` namespace. For general design principles for creating class libraries, see [Framework Design Guidelines](../../../standard/design-guidelines/index.md). +These guidelines do not preclude general design principles for class libraries. Rather, they are recommendations that are optimized for developers who are using Visual Basic and the `My` namespace. For general design principles for creating class libraries, see [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines). ## Packaging and deploying extensions diff --git a/docs/visual-basic/programming-guide/program-structure/coding-conventions.md b/docs/visual-basic/programming-guide/program-structure/coding-conventions.md index a4aba86422ea8..800f13163521e 100644 --- a/docs/visual-basic/programming-guide/program-structure/coding-conventions.md +++ b/docs/visual-basic/programming-guide/program-structure/coding-conventions.md @@ -22,7 +22,7 @@ Microsoft develops samples and documentation that follow the guidelines in this ## Naming Conventions -- For information about naming guidelines, see [Naming Guidelines](../../../standard/design-guidelines/naming-guidelines.md) topic. +- For information about naming guidelines, see [Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries](https://aka.ms/dotnet/framework-design-guidelines). - Do not use "My" or "my" as part of a variable name. This practice creates confusion with the `My` objects.